Comment by hermitcrab
7 hours ago
That is a good point. The more documentation there is, the harder it is to keep up to date. It also perhaps works against getting the best design, because nobody want to go back and change all the documentation. An argument for keeping the documentation fairly minimal, perhaps.
I like making good docs, and i appreciate good docs when i find it. I think alot can be done to make docs easier to maintain and more useful.
When approaching a large cryptic codebase, the intention and assumptions are usually more important than the details. And these are really quite simple to write down.
- Goals a Problems
- Constraints
- Chosen high level approach
- Relevant files, functions and resources.
- Future concerns
There is the worry about maintenence, but i think the history itself may be valuable.
If a design change happens, or a new major thing is added on-top, make a new document and timestamp it.
Over time this becomes a repository and history of the design and current state of the system.
Its harder to read and understand than a properly updated doc that is reflective of the current state, but its orders of magnitude better than not making docs because its annoying.