When I was young, documentation came in one form (only). Books. Getting a good reference book was the key to progress. I still have my 3-inch thick C and C++ reference books on my desk today. (They're under the monitors lifting them up 3 inches.) I remember reading them cover to cover multiple times, and using them regularly every day looking up details.

Then came MAN pages, which are hard to read, harder to digest. Quality varies from good to rubbish. Early F1-Help much the same.

Then we got Google, and Stack overflow, and now AI. All of which make for better reference (quick answers to quick questions) but Discoverability harder. (I've started asking AI foe "tell me something I don't know".)

99% of the programmers I encounter don't write docs at all. Programing is Math not English. For my sins I likely write more docs than code. But I've also discovered a hidden truth. Writing docs makes my code better.

When you document you formalize something. If the docs are clumsy that means the thing is clumsy. I cannot count how many times, while writing the docs, I discover "this is harder / uglier / more confusing / inconsistent than it needs to be." Which is a cue to improving the code.

Even the documentation becomes elegant, then the solution is elegant. Not before.

You almost had me there…

Recommended to frighten the younguns, with their tiktoks and their yootubes.

For what?