Best Practices for (Architecture) Documentation

Architecture documentation often falls behind because it is time-consuming, laborious and quickly outdated. The Documentation as Code approach turns this around: Documentation is maintained in lightweight text formats directly in the code repository, built automatically and delivered via the CI/CD pipeline. Even diagrams can be written as text, versioned and integrated into review processes - a relief for developers and a benefit for anyone who relies on up-to-date documentation as a basis for software testing.

Podcast Episode: Best Practices for (Architecture) Documentation

In this episode, we talk about the importance and methods of efficient architecture documentation. We discuss how documentation is often neglected and what solutions are available to avoid this. The ‘Documentation as Code’ and ‘Continuous Documentation’ approaches make it possible to treat documentation like source code and update it continuously. We also look at the use of tools such as Markdown and ASCII-Doc, which simplify the process of creating and maintaining documentation. Numerous practical examples and tips are used to illustrate how developers and testers can make their documentation lightweight and effective.

“Word is not made for writing big things.” - Falk Sippach

As a software architect, consultant and trainer, Falk Sippach is always on the lookout for the spark of passion that he can ignite in his participants, customers and colleagues. He has been supporting mostly agile software development projects in the Java environment for 20 years. As an active part of the community (co-organizer of the JUG Darmstadt and member of the Java Champions), he also likes to share his knowledge in articles, blog posts, as well as in lectures at conferences or user group meetings and supports the organization of various specialist events.

Highlights der Episode

• Architecture documentation usually fails due to the wrong tools, a lack of prioritization and a lack of fun when writing.
• Documentation as code: Write docs in Markdown/AsciiDoc, version in Git, build automatically.
• DrawIO saves vector data in PNG metadata - remain editable without a separate export step.
• Diagrams as Code with PlantUML makes diagrams versionable, comparable and reviewable like source code.
• Definition of Done must contain documentation updates - otherwise it fails the code review.

Efficient architecture documentation

In this podcast episode, I talk to Falk Sippach about the importance and challenges of architecture documentation. Falk introduces lightweight approaches such as ‘Documentation as Code’ and ‘Continuous Documentation’ that help developers manage documentation more efficiently.

Introduction to the world of architectural documentation

Hello and welcome to the new episode of our software testing podcast! I’m Richie, your host, broadcasting live from OOP 2024 in Munich. This time I have Falk Sippach as my guest. We had an in-depth discussion about architecture documentation - a topic that is also very important for us testers. Documentation serves as a test basis and reference work, which is why it is indispensable. In our conversation, Falk presented valuable approaches on how to design lightweight documentation.

Why documentation is often neglected

Falk has addressed a problem that many developers are familiar with: Documentation is often seen as secondary. Priorities are often placed on the completion of projects and less on documentation. Many developers find writing documentation a chore compared to the actual programming. In addition, the tools required for this are often not optimally integrated. A survey during his presentation confirmed the many reasons: high effort, complicated tools and the assumption that nobody reads the documentation anyway.

Lightweight approaches: Documentation as Code and Continuous Documentation

Falk presented two central concepts: ‘Documentation as Code’ and ‘Continuous Documentation’. With ‘Documentation as Code’, documentation is treated similarly to source code. This means that simple text formats such as Markdown or AsciiDoc are used and integrated into existing build processes. The second approach, ‘continuous documentation’, aims to integrate documentation work iteratively and incrementally into the development process. This means that the documentation is always up to date and is continuously improved.

Practical implementation of Documentation as Code

According to Falk, the implementation of ‘Documentation as Code’ is surprisingly simple. No additional tools are required; text editors or IDEs are sufficient. The documentation is written in text files alongside the source code and can then be automatically processed into PDFs or HTML pages. The modularization of the documents is particularly valuable here, which keeps them clear and easier to maintain.

Integrate diagrams efficiently

A picture is worth a thousand words - this is especially true for technical documentation. Falk explained various methods for integrating diagrams: From simple binary formats such as PNG or JPEG to vector graphics with DrawIO or PlantUML. The latter even allows diagrams to be written as text and integrated directly into the source code. This means that everything remains versionable and traceable.

Continuous documentation as part of the development process

A central point of our discussion was how to integrate ‘continuous documentation’ into the development process. By integrating the generation of documentation into existing build processes, it always remains up-to-date. CI/CD pipelines can be configured so that every change in the source code automatically updates the corresponding documentation. This not only ensures consistency but also increases acceptance among developers.