Programmers at work: I bought a used copy of it - probably after reading this the first time it was posted. Great book, if you can find it.
Code, by Charles Petzold should be on any programmer’s list - and the list of anyone with curiosity about how the modern world works. It somehow manages the amazing trick of being readable for the novice, but also containing nuggets of insight for the expert all at the same time. Such a well written book.
Yeah, this feels like one of those ‘explainers’ that feel like they are great to someone who already knows how the system works, but don’t actually work for newbies because they tacitly assume knowledge of the shape of the system that seems ‘obvious’ to someone steeped in it.
This is a problem with most docs I encounter. _Good_ documentation should also teach the user how to use the thing, not simply end up as glorified out-of-band code comments.
I found that it's a mistake I would often make when writing documentation about something I deeply understand. I forget the questions that led me to that understanding. Now I make a conscious effort to think about the knowledge of the intended audience. I still miss things, but that's why it's good to have other people review.
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.
There is a big difference, IMHO, between an "explainer" and "documentation".
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.
Bad documentation has been out there for as long as I can remember. The problem AI seems to be adding is the expectation of “just ask an AI” which is removing the drive to write even bad documentation and expecting the AI to derive answers from code and API references.
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.
For me this one looks like someone prompted: “I want to have a cool looking explainer in form of a website and make it about hot topic”.
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.
Despite all the sound and fury online, Golden Gate will also run just fine on the M1. They're barely less powerful than the current Neo - and usually have more RAM.
I’m building a shed at the moment, and it’s become basically impossible to find reliable advice on tools or techniques by searching the web. It’s all just slop feeding back on itself now, unless you are lucky enough to find a forum post from before, say, 2023.
For example, try searching about what sort of nails you should be using to attach cedar lap siding.
On Google, you might find a few good results, but you’ll really need to scrutinize them to make sure they’re reliable. Most are slop on the ‘blogs’ of siding and roofing contractors.
On DDG, it’s even worse. Usually nailerguy.com ranks highly - it seems to be completely AI generated, complete with contradictions and impossible pictures. And, often, nailicy.com, a (seriously) nail salon in New Hampshire that I’m sure is confused about why all their web traffic isn’t translating into clients.
YouTube is about the only ‘reliable’ source for recent advice.
Have you tried going to a library or a bookstore? Or even Amazon, since the return policy is excellent. Books are still a reliable resource for anything that hasn’t changed in the last 5 years (since there will be a pre-LLM text). Fortunately that includes loads of DIY tasks.
Don’t get me started on Google’s propensity to show a full page of unwanted shopping results now without any way to show websites unless you turn verbatim on. “Brand picks” what garbage.
Thank you for mentioning DDG - I don’t know what it is about their search algos but whenever I tried switching I found I got far less helpful results compared to Google. Like at least half the first results were total slop fest unusable.
DDG has become so unusable because of AI word vomit sites that I'm finally seriously considering the paid search engine that HN loves... Kagi, I think?
That the process is sharply biased towards negativity is a cogent criticism.
Two alternatives:
- Trust our representative system and have our elected representatives make decisions (ha! Although perhaps people would pay attention to local elections more if they had more direct consequences…)
- Randomly select people to comment, like jury duty.
It’s not impossible to think of systems that take public opinion into account that are not the exact system we have now.
With public comment, politicians will still just do whatever they want without accountability
This is very obviously not true to me. Is there really nothing in your area that’s been cancelled or interminably held up by the public comment process?
This is also what we lost in the field of music, with the switch from radio to streaming.
With radio, you used to have to sometimes sit through music you didn’t like so much, with the upside that you often discovered things you didn’t know you liked.
Code, by Charles Petzold should be on any programmer’s list - and the list of anyone with curiosity about how the modern world works. It somehow manages the amazing trick of being readable for the novice, but also containing nuggets of insight for the expert all at the same time. Such a well written book.
reply