[whydoyoucare]

I believe it is equally important to determine the level of abstraction for the documentation, such that updating it is an infrequent task (essentially, every line of code change should not trigger a document change). It is easier said than done, but that's the best compromise I have arrived it.

At the very least, the document should capture high-level (again this is relative term) design, possibly an architecture diagram of major interacting functional units. The success measure should be the relative ability to build a mental model of the system by looking at this document for any newbie.

That design document would be a start, and most likely not "quickly outdated".

My personal beef with the agile camp is precisely this: when they let go of documentation, they don't do the design doc as well, and all that remains of the system is thousands of incoherent stories and huge amount of code.

[dkersten]

If you document via design logs and decision logs, then you don't need to document every line of code because its already done in the design log. If something unforeseen arises, then you have a discussion, make note on the outcome in a decision log and move on. That is, the documentation logs proposed decisions and outcome decisions, which should contain enough context that you can read them in isolation. Then you don't need to worry about documenting as you're coding or documenting the code.

If you diverge too far from the original design, you should probably have a rationale as to why, that gets reviewed by others: another design log and decision log.

These documents don't need to be long either, just a couple of sentences for each of context, what you propose, impact on other teams or systems, decision made may be enough for smaller things (so a paragraph or two) and for larger changes, you probably need the detail for everyone to really understand what, why and its impact. The alternative is to do these things blind.

> when they let go of documentation, they don't do the design doc as well, and all that remains of the system is thousands of incoherent stories and huge amount of code.

Absolutely agreed.