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.
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.