We’ve several suggestions, but the most important one first:

Appoint a person responsible for the appropriate amount and quality of your technical and/or architecture documentation.

  • Document economically, especially be frugal with building block details: Many developers will understand many details of building blocks by digesting source code - so don’t create a large number of whitebox diagrams.
  • Level-1 of the building block view will be one of your best friends: That top-level structure of your system will most often remain quite stable over time, and won’t need to be updated often. Many source code changes don’t affect level-1!
  • Defer documentation of volatile parts: In case you can anticipate structural changes or volatility in certain parts of your system, leave the documentation of these parts as abstract and high-level as possible until these parts have reached a stable state.
  • Prefer documenting “crosscutting concepts” (arc42 section 8) over detailed building blocks (section 5) or runtime scenarios (section 6).