Software Design document
A Software Design Document or Architecture Document is a piece of Technical writing that defines a plan for solving a problem with software. It is necessary because software is so complex and requires so many decisions and trade-offs, it cannot be inferred from reading source code.
Should be written by project lead, for projects that take 1 engineer month or more.
Note that designing a very complex system entirely upfront and expecting it to work generally guarantees failure. Instead, very complex systems that work will emerge over time from simpler systems that work.
Examples of great design documents
Beware, all these examples were written after the software was made, and architecture documents are generally written before a project starts. Real architecture documents made for planning are generally kept secret.
- AWS This is my Architecture
- Bash shell's Architecture by Chet Ramey
- GitLab's Architecture Overview
- Stack Overflow, on Nick Craver's blog.
More at The Architecture of Open Source Applications.
Components of a design document
A convenient location and format
Future maintainers will want to read it. Thus it's worth placing it somewhere they can easily read it. One recommendation is to make a file called
ARCHITECTURE.md in the software repository, adjacent to its
Significant files and modules should be mentioned by name, but not linked directly as such links can expire. Searching for the name encourages future maintainers to explore.
Invariants or exclusions
If you have intentionally excluded something from the design, that thing should be defined along with the reason why. Future maintainers cannot know why something doesn't exist.
These might be based on the C4 model: context, containers, components, code. Personally I prefer to rename context to customers. InfoQ has a guide to the C4 model.
Guides to writing architecture documents
The open source arc42 document framework is considered by many to be the best. Features many examples and is entirely free to use. InnoQ has a guide to using the framework.
Free Code Camp has a guide: How to write a good software design doc
This says that this is good
"As a general rule of thumb, if you are working on a project that might take 1 engineer-month or more, you should write a design doc. But don’t stop there — a lot of smaller projects could benefit from a mini design doc too." How to write a good software design doc ↩︎
"If you maintain an open-source project in the range of 10k-200k lines of code, I strongly encourage you to add an
ARCHITECTUREdocument next to
CONTRIBUTING." ARCHITECTURE.md ↩︎
"Explicitly call-out architectural invariants. Often, important invariants are expressed as an absence of something, and it’s pretty hard to divine that from reading the code. Think about a common example from web development: nothing in the model layer specifically doesn’t depend on the views." ARCHITECTURE.md ↩︎