Comment by aDyslecticCrow

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.