Architecture Documentation

Architecture Documentation as Code

Architecture documentation is supposed to help developers understand the bigger picture. It should convey a cognitive model into which technical details fit without contradiction. Unfortunately, many solutions for understanding or documenting architecture come with their own structures, notations and tooling which is often detached from cognitive structures that developers are already familiar with like repositories, folder structures, markdown files and Git-based version control. This can be solved by integrating architecture documentation directly into the codebase as markdown files:

• Unified Change Process: Storing architecture documentation in markdown files unifies the change process for code and documentation and allows to change both in one pull request.
• Architecture Version History: The version history stores the whole architectural evolution.
• Easily Accessible: Developers who check out the code have easy access to the documentation within their IDE.
• Folder Structure Context: Folder structures are used to provide a context structure for code. The same structure can be used for architecture documentation.

Integrating architecture documentation into the folder structure of the codebase can look like this:

📁 components/
  📁 my-app/
    📄 README.md
  📁 my-library/
    📄 README.md
  📁 my-cloud-resource/
    📄 README.md
📄 README.md

Markdown files can contain links to other markdown files. The top-level README.md can provide an overview and links to nested markdown files. This basically turns the documentation into a wiki-style portal with the top-level README.md being the overview page.

Shared Knowledge with Developers

Documenting architecture knowledge is helpful to create a shared understanding among developers. This has multiple benefits:

• Onboarding
  • Comprehensive learning material for new developers
  • Developers can learn at their own pace
  • There is a clear expectation what knowledge developers are supposed to know to do their job
• Prevent Knowledge Silos
  • Knowledge silos can be used as a tool to gatekeep information to gain an advantage.
  • This is highly destructive to a generative team culture.
• Prevent Hero Culture
  • Not sharing knowledge can create hero developers who know basically everything while the rest of the team always has to ask them for help.
  • Hero developers become productivity bottlenecks for the whole team.
  • Hero developers can become unmanageable ("We fired our top talent. Best decision we ever made.")
• Architecture Decisions
  • Document architecture decisions
  • Propose architecture changes by opening a pull request
  • Discuss architecture changes using the documented knowledge as baseline

Shared Knowledge with Non-Technical Stakeholders

Providing non-technical stakeholders with a high-level system overview that spares out technical details has an important psychological effect: It invites non-technical people to learn and deepen their technical understanding and it demonstrates that developers are willing to help with it. A top-level README.md that gives an overview without too much technical details should be readable by non-technical stakeholders. Various non-technical stakeholder perspectives benefit from this:

• Product Management: Aligning strategic product decisions and roadmaps.
• Design: Understand usability structures and constraints that designs needs to align with.
• Legal: Ensuring privacy compliance by understanding how data is collected and transferred.
• Accounting: Understanding and predicting operational expenses.
• Marketing/PR: Communicating customer expectations on roadmaps or technical decisions
• Sales: Establishing communication with development teams to convey customer feedback and get answers to technical questions.

Shared Knowledge with AI Assistants

The rise of Large Language Models (LLMs) lead to the development of AI assistants that can parse human language and be asked to generate code. However, these assistants need to be provided with proper context information to guide the code generation. This is done by extending the prompt that is passed to the LLM with additional context about the architecture:

My take away from this discussion was that using chain of thought and generated knowledge prompting approaches can be a significantly useful tool for programming. In particular it shows that to use LLMs well, we need to learn how to construct prompts to get the best results. This experience suggests that it's useful to interact with the LLM like a junior partner, starting them with architectural guidelines, asking them to show their reasoning, and tweaking their outputs as we go. - Martin Fowler: An example of LLM prompting for programming

In order to properly guide an LLM it needs to be provided with a written, comprehensive architecture onboarding text. While human developers can puzzle together multiple information sources such as discussions, diagrams, texts or code comments, an LLM needs this information as part of its prompt. Integrated markdown documentation is suitable for this because LLMs can understand markdown and the semantics of its formatting such as nested lists to express hierarchies or links to refer to other information sources (tested with GPT-3.5).