Overview

In this first article I want to set the scene by outlining what living documentation is, and the types and flows of knowledge in the engineering process. Future articles will cover currently available tooling and options.

So let's get started and cover some basics to all get a common understanding on:

• Definition of Living Documentation
• Forward and reverse engineering
• Maintenance and customer documentation
• Design evolution
• History of living documentation

Definition Of Living Documentation

The key elements of living documentation are:

• Living — it is up to date and reflects the current state of the software
• Documentation — it is a collection of descriptions regarding the requirements, architecture, design, implementation, and operation of the software system.

There is no formal definition covering:

• What it should include
• How it should be formatted
• How it should be structured
• How it should be maintained By formal, I mean an ISO or ANSI standard, or even a book that has been accepted as best practice, or a tool that has gained widespread acceptance and offers a universal solution.

This doesn’t mean that these topics haven’t been discussed, requirements clarified, or point solutions available.

Cyrille Martraire in his book describes the key principles of living documentation as being:

• Reliable
• Minimal work to produce
• Collaborative
• Insightful

At this stage, it is worth looking at traditional engineering practices and the types of documentation produced to set the scope.

Forward Engineering

In traditional forward engineering (left to right) tasks are done in a sequence. This is true for waterfall where an entire stage is completed for the entire product before the next stage starts. The output from one phase is typically documentation (as a discrete document or within a tool) and this forms the input to the next stage. The final output is source code which may or may not include the output from the previous design phase. This design may be a simplified text-only description of the design, such as function descriptions or pseudocode. For agile projects then the process is still similar but executed on very small amounts of software, and several of these can be in development concurrently.

Reverse Engineering

Reverse engineering is often associated with situations where a team is trying to modify an undocumented software product. Large products are hard to understand so a tool may be used to statically analyse the codebase and simplify it into hierarchical function calls and classes. The interpretation of the design can be a mix of diagrams and text and include relevant code extracts or references. In addition, these tools can highlight anomalies, such as functions and methods that are not called, variables that don’ appear to be ever used.

Maintenance

When software moves into the support and maintenance phase then pressure from customers and the need for rapid response tends to decrease the amount of design and increase reliance on helpdesk tickets.

Customer documentation

There is also a requirement for some documentation for customers, such as release notes, FAQs, user manuals, and online help. This is typically done by a technical author and is based upon real-life use of the product, company standards for customer documentation, information from helpdesk tickets, internal release notes, and specifications. Software source code traditionally never feeds into this activity as the authoring team is unlikely to be able to understand it, and it is unlikely to include design information in a format that can be easily understood.

Design evolution

Photo by Eugene Zhyvchik on Unsplash

The world of software design has gone through various steps in its evolution and the BDD transition is a critical connecting piece in the living documents puzzle. These design steps can be summarised below:

• TDD Test Driven Design — write a test, run the software, watch the test fail, write software so the test will pass
• MDD Model Drive Design — focuses on abstract representation rather than the software concepts, and favoured large CASE (Computer-Aided Software Engineering) tools in the 1980s and used UML to describe details.
• DDD Domain-Driven Design — includes knowledge of that domain, terminology, context, and its boundaries. DDD is considered more abstract than MDD.
• BDD Behaviour Driven Design — a way to define the dynamic behaviour of a system using domain-specific terms such that the requirements can be traced to test scripts and executed

BDD is arguably one of the biggest steps as the simple format for documenting features and scenarios using Given-When-Then syntax from a simple ASCII text file. This simplicity allows people to interact with it using any number of standard tools and also for it to be automated and transcribed into instructions for a test automation framework.

A brief history of the journey to Living Documentation

-1921 Flow process chart presented by Frank and Lillian Gilbreth
-1963 Flow chart standard by American Standards Association, Article on Techniques of Flowcharting by Louis A. Schultheiss
-1970's Data Flow Diagrams and Context Diagrams, Yourdon and Constantine
-1975 book Principles of Program Design, Jackson.
-1985 Sidecar files used in AmigaOS with Meta data, ISO5807 standard for flow chart symbols
-1997 Doxygen tool started, UML v1.1
-2003 JBehave (replacement for JUnit) developed, JavaDoc released by Sun, book Domain-Driven Design by Eric Evans[5]
-2004 BPMN v1.0 released,
-2005 RSpec (BDD for Ruby)
-2006 Article in Better Software magazine by Dan North on BDD [4]
-2008 Cucumber (BDD for Ruby)
-2009 Specflow (BDD for .Net)
-2011 Book Specification by Example[1] [3]
-2018 C4 Architecture Model published
-2019 Book Living Documentation[2]

[1] Specification by Example, Gojko Adzic,(2011) ISBN 9781617290084
[2] Living Documentation, Cyrille Martraire (2019) ISBN 9780134689326
[3] Reflection 10 years on (2021) https://gojko.net/2020/03/17/sbe-10-years.html
[4] https://dannorth.net/introducing-bdd/
[5] Domain-Driven Design: Tackling Complexity in
the Heart of Software by Eric Evans

Further Reading

• Book Review - Living Documentation by Cyrille Martraire
• Buy book on Amazon

More About The Author

Greg is an experienced software professional and CTO at outsource.dev , having worked in several businesses he is now passionate about helping others succeed in software development, management, and outsourcing.

If you enjoyed this article then please like it and follow me.