Aphorism for better developer documentation
You write documentation for a single audience.
A single document for all audiences is bad documentation.
Developers are the audience of developer documentation. Not users. Not managers. Not project managers. Developers maintaining the system. You write for developers.
Your goal is to write clues to help the developer discover the system themselves.
Documentation are clues because it is impossible to describe the system in its entirely.
All projects that attempt to capture it all, will always fail.
Write documentation for yourself, reading it at 3 AM, fixing production.
Self-documented code is not enough documentation. Code describes what is happening. It can't tell you what the intention was.
Unit tests are not enough documentation. Tests encode requirements at a moment in time. Requirements change.
If your code is correct, but it looks like a mistake, write a comment explaining why it is correct and the danger of changing it.
Document intent. Code can be self-documenting, and appear correct, but it might do the wrong thing. Add a comment describing what you intended to do.
Notice when you explain verbally your system to a coworker. That is what you need to write down as documentation.
Describe your system in short articles. These articles should live in your repo, under a documentation folder.
Include the history of the project, especially when the history explains an architecture and code that look like a mistake.
Keep old documentation. Mark it "HISTORIC". Move it to a "history" folder if you wish. These documents give clues to the history of the system.
If someone asked you to explain some part of your documentation, that is a signal that you need to update that part of your documentation.
You grow documentation like a garden. You are never done.
If you prefer bullets for the main points of this entry, then
Write for developers
Share intent
Describe your system
Explain what looks like mistakes
Tell the system's history