Engineers rarely consider either, and doing both requires significant work

No MS, I don't want to ask co-pilot. Why don't you get co-pilot to draft some good documentation, that you then review and edit to make sure it is accurate, instead of expecting every individual to ask an AI for every question they have? That would be a lot more efficient in terms of energy use, I expect.

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.), 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, sometimes you need that with branches (links) off to longer introductions to specific parts, it depends on the size of the project.

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.

I don’t like people pointing out AI slop but one looks like something that should be called out. Maybe it helps the author for self learning that’s cool, but it doesn’t look like something for sharing with people as it really only wastes time.

They both provide stateless RPC methods and human readable metadata that makes them easy to route.

You could ask why json-rpc was even necessary for 2.0. I think mostly just for stdio and backwards compatibility.

From your comment, I expected to be annoyed by a bunch of slop or obscurities.

My guess is the writing did not come straight out of an LLM and was carefully curated.

If I’m wrong I’d love to have the style prompt.

The opening has 1 paragraph and 5 table entries. One of them is “Not REST”

It’s a little scary that this was considered too dense or complex because the basics were explained in something that could be read in 1 minute. That still wasn’t enough to stop the top HN comment (as I write this) from calling it too dense and giving incorrect information that is immediately refuted by skimming the top part of the article.

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?

If the article said, "It's basically just REST". There'd be no need to comment as such.

Yeah, I can click around and follow what's going on. But I'm with GP: this is not making it easier to understand. It's great at being Hollywood UX: looks pretty, stuff moving everywhere. One click on "step" makes the image animate, and change the text in the left sidebar, top middle, and right sidebar, in addition to stepping the table in the bottom middle. But it's almost the opposite of distilling information

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.

and yet...

Maybe it was written for an AI? :)

Or by an AI? Or both?