A software architecture doc (e.g. ARCHITECTURE.md) is a way of stating the overall structure of the code. This makes it easier for new people to ramp up on the code base and trims down the time it takes to find where to make a code change.
Best practices:
- Keep it short, the longer it is the less likely is to stay up-to-date
- Specify the things that are most unlikely to change (again to keep it up-to-date), this also gives a frame of reference like landmarks on a map
- Don’t link directly to code since links go stale
- Make it highly visible so engineers go read it often
See also:
- Software architectural patterns, having a cohesive architecture makes it easier to document
- It should be obvious to spot if there is conceptual integrity by reading the architecture document