Best Practices for (Architecture) Documentation

I talk to Falk Sippach about the importance and methods of efficient architecture documentation. We discuss how documentation is often neglected and what solutions are available to avoid this. Falk explains the ‘Documentation as Code’ and ‘Continuous Documentation’ approaches, which make it possible to treat documentation like source code and update it continuously. We talk about the use of tools such as Markdown and ASCII-Doc to simplify the creation and maintenance of documentation. With many practical examples and tips, Falk shows how developers and testers can make their documentation lightweight and effective.

“Documentation as code is the idea that we can treat documentation like source code, i.e. we can use the same tools and also integrate and automate the whole thing in build processes.” - Falk Sippach

Falk Sippach is a software architect, consultant and trainer who is always on the lookout for that 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 presentations at conferences or user group meetings and supports the organization of various specialist events.

Highlights of this Episode:

• Documentation is important for testers as a test basis and reference work.
• Falk explains how documentation is often neglected and why this is the case.
• Documentation as code means treating documentation like source code and writing it in text formats such as Markdown or ASCII Doc.
• Continuous Documentation integrates documentation into the entire development process, similar to Continuous Integration and Continuous Delivery.
• Integration of images and diagrams into the documentation

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.