Code Architecture Docs Decrease the Time Spent Searching for Where to Make a Change

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

Read the HackerNews thread

See also: