alt Hacker NewsI've written so much documentation over the years, and humans always come and ask me questions that the documentation answers, but never ever read it.
Replies
For me, the primary purpose of documentation is to help myself in the future.
I don't view it as something I'm writing for someone else anymore.
Ultimately, I think that's helped me write better documentation.
Writing for an imaginary audience is typically harder than writing for a concrete one, and things you might think "someone else" might need to know - they either 1) don't, or if they do 2) won't read your docs anyway, most of the time.
When someone asks me a question that is or should be documented, I like to ask where they looked for it (link or search query).
* Sometimes, this prompt is enough for them to find the answer.
* Sometimes, they tell me a spot that makes sense to them, and I make it have the answer. (Maybe just by adding a cross-reference.)
* If they refuse to look at the docs, I can't help them.
It's survivor bias though. If they read it and did the thing and never bothered you, you wouldn't notice that.
At some point I started to include jokes in documentation to encourage people to read it. For the most part, this only entertained whoever the knowledge or project admin was.
I have a pretty decent readme on all projects, and a /docs folder for key areas that need specific instruction on complex ones.
My boss was looking at them, but even the simple ones he was pointing claude at it and asked it to make a document explaining it. Then he'd send me the document and ask me to check if it was accurate. I added a line to the last page "this is an ai summary and may contain mistakes. Use the project readme for validated information" and told him it was grand.
If it helps, I have found the attitude that writing is mostly for the writer to be healthy in continuing the practice. And it largely tracks with how I feel I have had better understanding of things I have documented than those I have not.
Exactly. I recently found out I can use Atlassian‘s ROVO to ask questions against our Wiki and Jira. I now forward consultants to ROVO first and only if they can’t find an answer then I’d look at their questions. Saves me a good chunk of time. They never read my docs otherwise.
Always fun collaborating with someone on a project and having them surprised you actually read their documentation and checked out their code instead of expecting them to explain everything from the ground up.
How searchable is it.
Same, but at least I benefit from my own docs when I revisit code, and now my agents do. These days they do the writing for themselves anyway, I get to review and think about the big picture. I'm def happier this way
Turns out all this time you were writing for AI to read!
It's been this way since the beginning.
That's why Usenet is full of posts reading "RTFM."
For some reason, instead of telling people to do that, which solves the problem, we just stopped writing manuals altogether.
Very often that is a sign of poor UX, or that the documentation is in the wrong place.
Right, this seems like an obvious conclusion - what is the outcome of the person writing the docs in either case: