|
|
|
|
|
|
by codegladiator
391 days ago
|
|
|
I've been using this obscure tool called "documentation" for years now. It's this revolutionary concept where the people who created the software actually write down how it works! Sometimes it even has examples showing how to use the software correctly. I know it sounds too good to be true, but trust me once you discover documentation, you'll wonder how you ever lived without it. |
|
|
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.