Right, this seems like an obvious conclusion - what is the outcome of the person writing the docs in either case:

  1. Immediate better output from the machine OR...
  2. Being sidelined for career promotions because you spent so much time making sure documentation was accessible while everyone knows they can ask you instead of reading it, and you will answer.

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.

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.

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.

This is not very surprising. The docs you write can only help if the person who is reading it have the same mental model of what ever thing that is being documented. Because the questons they want answered arises from what ever little subset of understanding they have of the thing. And this could be different for different people.

And this is why LLMs are great for looking up docs. It makes any docs work for any one as long as the information is present in the doc.

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.

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.

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.

Yup. Claude will rtfm. Most humans won't.

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

Very often that is a sign of poor UX, or that the documentation is in the wrong place.