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.[1]

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.

More at The Architecture of Open Source Applications.

https://johnjago.com/great-docs/
https://news.ycombinator.com/item?id=39819409

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 README.md. [2]

Dependencies

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.[3]

Diagrams

C4 diagram for internet banking system

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.

diagram

https://www.unravelled.dev/how-architecture-diagrams-enable-better-conversations

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

https://www.workingsoftware.dev/software-architecture-documentation-the-ultimate-guide/
https://news.ycombinator.com/item?id=34482836

More reading

https://martinfowler.com/architecture/

This says that this is good

https://www.workingsoftware.dev/architecture-principles/?ref=refind

https://blog.pragmaticengineer.com/software-architecture-is-overrated/
https://news.ycombinator.com/item?id=21001676

  1. "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 ↩︎

  2. "If you maintain an open-source project in the range of 10k-200k lines of code, I strongly encourage you to add an ARCHITECTURE document next to README and CONTRIBUTING." ARCHITECTURE.md ↩︎

  3. "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 ↩︎