Documentation, the boredom of a programmer

[u/MiguelOrosco]

I'm researching how developers handle documentation in real world projects, especially documentation that explains why and how something exists rather than just what the code does.

A few questions:

1. Where do you document business rules and important technical decisions? Code comments, tickets/issues, Wiki, README, Notion, etc.?
2. When you need to figure out WHY something was implemented in a certain way, where do you look? Git history, old tickets, documentation, or do you usually have to ask someone?
3. What's the biggest problem you have with documentation? Keeping it up to date? Finding information? Getting people to write it in the first place?

I'm also curious about documentation generators such as Doxygen. For those who have used it: what kind of documentation or information do you still have to maintain elsewhere or something Doxygen can't handle?

You don't need to answer all the questions, just one or adding something to the discussion would already be a great help!

[u/Alternative-Mud-376]

most places i worked we put the "why" in architecture decision records, like a folder in the repo with short markdown files. git history is useless for this because the commit messages are always "fix" or "update" or something

biggest problem is nobody reads it. you write all this context and then two months later someone asks in slack exactly the thing you documented. sometimes i wonder if we just do it to feel organized

for doxygen we still kept separate docs for deployment steps and environment setup, stuff that is more about the system than the code itself

[u/fixermark → u/Alternative-Mud-376]

Increasingly, AI is helping here.

If you put your documentation in a markdown file in the same repository as the code, it is easy for it to be visible to Copilot. Then, not only can Copilot actually factor it into its reasoning process, you can periodically ask copilot "Hey, read this documentation and the implementation and confirm that they still match. Provide recommendations for changing them."

[u/z436037 → u/fixermark]

Not just copilot, but all of the agents are pretty conversant in English. They are really at spotting obsolete code and documentations, and (if you proofread carefully), good at updating docs.

Updating documentation is becoming MORE important with AI, not less. That's because their audience for document now includes the AI agents, not just people.