Most documentation is reference documentation, which as you find it not very useful for just starting out (it assumes at least a small base of knowledge about what it is documenting).

> _Good_ documentation should also teach the user how to use the thing

Good documentation usually comes in at least two parts: guide/introduction and reference. This is how some of the better ORA books were written, back when dead trees on shelves were a key source of learning for programmers - three sections: a small one for absolute basics (what you need to know before starting, many could skip this), the second an introduction to the concepts of the new thing (language, library, server, etc.) and what differentiates it from similar/related things, typically with worked examples, and at least the last half of the pages being reference material (split into meaningful subdivisions where that is useful). Sometimes they would split this in two and there would be explicit introduction and reference works (under the banner “complete reference”, though these would have a little introductory text in them too) for the same subject, but not always.

When you try to merge the two (guide and reference) too closely it all too often ends up either too basic or irritatingly long-winded for the experienced readers, while still being too opaque for those who are starting from scratch.

Sometimes a single good README is all that is needed for the guide part these days, sometimes you need that with branches (links) off to longer introductions to specific parts, it depends on the size of the project.

Engineers rarely consider either, and doing both requires significant work

For an article explaining a concept, it's a balance to find, and it depends on the target public. If every physics publication started by teaching physics to the reader, it just wouldn't work, would it?

Regarding documentation: we probably all agree that a code repository should NOT explain how programming works: if you don't understand C++, then a C++ codebase is not for you.

But should the README explain how to, e.g. run CMake? I would agree it shouldn't. Just like it shouldn't explain how to clone the git repository, or start the computer.

This said, I find this particular explainer about MCP... convoluted.

https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...

What does that even mean?

> the same request/response format as REST

What request/response format does REST have?

Do you even know what HATEOAS means?

Agreed, and it probably doesn't need to be overwhelming but the design choices leave the intent and purpose of the UI fairly unclear. It requires a bit of clicking around to understand what it's all for, and it's quite flat and unappealing, leaving little drive to do that work.