Hacker News Reader

Comment by ocimbote | Hacker News Reader

Any kind of documentation has a target audience. Your test is very valuable if and only if the target audience is a total beginner. Of course it's still very hard to write good documentation even if you have identified your target, but having someone totally illiterate on the subject matter review your documentation is as useful as if I'd have to review a PhD thesis in quantum physics. It just doesn't make sense (trust me :).

Writing documentation is hard. Start with: Who am I writing this for?

edit: I may have misunderstood OP's "with minimal expertise" for "total beginner". They're two different things, absolutely.

View on HN

For most public documentation, you don't get to pick your audience. You think you'll have people with certain experience, but then it turns out you're wrong. Usually a lot of the time. And even when you're not wrong, having the steps essentially from scratch listed out reduces the number of times people get stuck, because they think about things they may have missed.

I cannot tell you how many times I've had to go through 30 hyperlinked pages of fluff explaining universal basic concepts before finding the five sentences I actually needed (buried in five different places).

And just as many where people explain in detail exactly how to do foo with bar without explaining why I would want to do foo in the first place and what a bar even is.

Way too much documentation is like this. Then again, lots of times asking coworkers about an existing system or a new ticket that's not detailed properly ends up with them saying 30 pages of fluff to me before I can get to the nugget

This really is one of those things that AI can improve, and already improves today.

As much as I'm not an AI booster, it has helped a lot when I hit a wall with poorly done documentation where the related bits I need are scattered all over and even a text search isn't helping me

I was gonna write something similar. Know the audience. I've also come to the conclusion that "total beginners" (and certainly "minimal expertisers") didn't nowhere to read the docs anyway so it didn't matter.

In other words, people who are used to reading docs can read (good) docs just fine.

Yes, of course, good docs are a must. They are critical to success. But not all docs have to explain how to use a right-mouse button.

Perhaps in addition to a description of the expected audience, it might be an idea to list some assumptions made about the reader? e.g. has installed software previously, confident with bash commands, &c

I almost systematically use BLUF (Bottom Line Up-front) when I write docs, I think I'll make TABLUF a thing from now on (Target Audience and Bottom Line Upfront) :)

The experts are likely to be skimming and interpolating your doc, so they'll get through it but you won't know why. You won't know if your doc works, or if it even addresses the subject matter. This is also true of academic papers.

My mom taught CS in the 1980s, and told her students on day one: "Computers are stupid, they will only do exactly what you tell them to do, not what you want them to do." Program code is, in a sense, a tutorial for an utter beginner. The benefit of coding is that you can do the "beginner test" over and over without wasting anybody's time, so you know that the computer will get through it. But an expert (including yourself) might read that code and never see that it does or doesn't work.

Reply on news.ycombinator.com