loading...

A minimal approach to software architecture documentation

simonbrown profile image Simon Brown ・2 min read

The question of "how much documentation should we write?" is popping up a lot recently, probably driven by teams looking at their business continuity plans, and the increase in remote working. Many software developers will be quick to tell you that:

  • "we're agile"
  • "we value working software over comprehensive documentation"
  • "the value is in the conversation"
  • "the code is the documentation"
  • "the tests are the documentation"

The code is the truth, but not the whole truth

As Grady Booch will tell you though, "the code is the truth, but not the whole truth". Although we should definitely strive for highly modular code, and naming that expresses intent rather than relying on comments, the code doesn't tell you things like:

  • What is the context of the thing we're building?
  • Who are the people using the project/product?
  • What interfaces does it have with other software systems, inside and outside of the organisation we work for?
  • Where is the software system deployed?
  • How do we support it?
  • What were the drivers that led the team to building the software system in the way they did?
  • What led to the early decisions being changed?
  • etc

Describe what you can't get from the code

With this in mind, and remembering that time is precious, here's my suggestion for a minimal set of software architecture documentation.

Consider this a starting point, and it should ideally be stored alongside the source code. If you need a few code level diagrams to document parts of your codebase, feel free to add some UML Class or Sequence diagrams. If you need to document business processes, then add some UML Activity diagrams, or perhaps take a look at ArchiMate. Ditto wireframes, entity relationship models, domain models, state charts, API definitions, etc.

Summary

Although statements such as "the code and tests are the documentation" is not necessarily incorrect, we should still strive to add something a little higher level, describing what we can't easily get from the code.

Posted on by:

simonbrown profile

Simon Brown

@simonbrown

Author "Software Architecture for Developers" | Creator of the "C4 model for visualising software architecture" | Founder at Structurizr | Software architecture training at architectis.je

Discussion

markdown guide
 

Together with our CTO we are looking into adopting the C4 model more and more from the start for our client projects. These articles really help!

In this particular case, I feel exactly the same around documentation. Although code can explain a lot, they cant explain everything. I think your list of minimum documentation is really good and helps.