How to Document Your Software Architecture

Tags:
2024 05 01 head

You are creating the next digital software masterpiece.

How can you document your software architecture in a way that is useful for your team and stakeholders?

A software architecture document SAD is a document that describes the structure of a software solution.

It includes the architecture of its components, the relationships between those components, and the principles that guide its design.

The solution architecture document is typically used as a reference for designing, building, and maintaining a software system.

Developers, architects, and other stakeholders use it to understand the overall design of the system and how it fits into the larger business or technical environment.

Below an example of a software architecture document content [1].

2024 05 01 architecture doc

Modern Approaches

Modern software development practices, such as Agile Manifesto and DevOps, have changed the way we think about software architecture [1, 2, 3, 4, 5, 6, 7, 8].

Tooling and practices have evolved to support the creation of lightweight, agile software architecture documentation. The arc42 approach natively supports Asciidoc and Markdown based documentation [2]. All documents are stored as text artifacts in a git repository. The documentation is generated as static website Asciidoc [3]. Diagrams with C4 Model or UML, Architecture Design Records ADR are linked to source code documentation.

The architecture documents shall be online, searchable and actual.

The artifacts shall be versioned to support documenting various releases of the application.

The documents shall be created as part of a continuous integration pipeline. This approach eliminates the need for manual documentation generation.

Architecture Documentation Goals

Software architecture documentation creates a common understanding of the solution behind the system for various stakeholders. The documentation makes it possible to evaluate the software architecture from the perspective of the various stakeholders.

Software architecture documentation supports architectural work and guides the development team in implementing new product features.

2024 05 01 C4 5 things

You should as a software architect understand:

  • What is the essence of Software architecture?

  • Why should the software architecture role include coding, coaching and collaboration?

  • What are the things that you really need to think about before coding?

  • How to visualize your software architecture using C4 Model?

  • How to document your application with a lightweight and collaborative approach?.

  • Why there is no conflict between agile and architecture?

  • What does just enough upfront design mean?

  • How to identify risks with risk-storming?

Documentation Rules

These are the rules for any technical documentation, including software architecture documentation:

  1. Write documentation from the reader’s point of view. Embrace approaches such as JavaDoc [4].

  2. Document that you have realized, not your wishes.

  3. Avoid unnecessary repetition. Reference and link to information, do not copy it. Minimalism is key.

  4. Avoid ambiguity.

  5. Use a standard structure such as arc42.

  6. Record rationale and decisions with Architecture Design Records ADR.

  7. Keep documentation current but not too current. Generate your documentation as a static website. Avoid manual steps when updating your documentation.

  8. Review documentation for fitness of purpose. A new collaborator in the team is the optimal guinea pig to test the documentation.

It is far better to be explicit and wrong than to be vague.

— Frederick Brooks jr.
1995

Possible Pitfalls

2024 05 01 arc42 c4

Upfront document everything

Do not document everything in advance. Think of the arc42 template as a cabinet for documentation.
You put something on a shelf as you work on it. This is how software architecture documentation emerges, evolves, and stays current.

Do not include tutorials or Q&A sections

The most important thing in arc42 is the structure. The structure does not provide a space for guides or Q&A sections.

Do not put any specific things like customer names or similar

Do not write customer-specific things in the software architecture documentation unless your building blocks are structured in a customer-oriented way.

Do not generate documentation site

Manual activities to generate the product documentation are a waste of time. Modern approaches are documentation as code and static site generators.
GitHub and GitLab provide the pages feature to host your documentation as static website. The generation can be integrated into the CI/CD pipeline.

Links

References

[1] D. Farley, Modern Software Engineering. Pearson Education, Limited, 2022 [Online]. Available: https://www.amazon.com/dp/B09GG6XKS4

[2] J. Bloch, Effective Java, Third. Addison-Wesley Professional, 2017 [Online]. Available: https://www.amazon.com/dp/B078H61SCH

[3] N. Ford, R. Parsons, and P. Kua, Building Evolutionary Architectures: Automated Software Governance, Second. O’Reilly Media, 2023 [Online]. Available: https://www.amazon.com/dp/B0BN4T1P27

[4] N. Ford, R. Parsons, and P. Kua, Building Evolutionary Architectures: Support Constant Change, First. O’Reilly Media, 2017 [Online]. Available: https://www.amazon.com/dp/1491986360

[5] C. Larman, Large-scale scrum. 2017 [Online]. Available: https://www.amazon.com/dp/0321985710

[6] C. Larman, Practices for scaling lean & agile development. Addison-Wesley, 2010 [Online]. Available: https://www.amazon.com/dp/0321636406

[7] C. Larman, Scaling lean & agile development. Addison-Wesley, 2008 [Online]. Available: https://www.amazon.com/dp/0321480961

[8] P. Clements, Documenting software architectures views and beyond. Addison-Wesley, 2011 [Online]. Available: https://www.amazon.com/dp/0321552687

1. I add a chapter describing the user manual and user interface when document our applications.
2. The worst solution is to write Microsoft Word documents and store them in a SharePoint site. Such documents can neither be searched nor archived. Jira wiki documentation has similar drawbacks.
3. I love Asciidoc and Hugo to create technical static website. I use plantUML and Mermaid to create diagrams.
4. JavaDoc lately added support to Markdown syntax and code snippets. It markantly simplifies the redaction of quality documentation.