Automating Software Documentation with Codebots

In the realm of software and system development, one significant challenge that persists is end-user documentation. As DevOps methodologies break down barriers to enable high-quality releases at speed, software teams often struggle to keep their documentation as up-to-date as the product itself. This is where WorkingMouse's Model Driven Platform Engineering tool - Codebots, steps in.

The Challenge of Documentation

Consider the mental capacity required when a simple addition of a new User Interface (UI) object may change one specific piece of documentation or, it may require changes across the entire manual, end-to-end. This creates a significant amount of workload.

A Bridge to a Solution

To solve this problem, WorkingMouse works at a higher level of abstraction, using models and pipelines that build bridges of automation for compounding returns of technical investment that squash technical debt.

Imagine only making a model change to update all documentation from a new release and that propagates, ending in a commit to an updated documentation repo!

The Importance of End-to-End Testing

Before we explain how we achieve this, it's important to understand the importance of end-to-end regression testing. Automated tests virtually run through a series of steps to mimic a user progressing through a system workflow to achieve a goal. These are important to ensure that a system's behaviour doesn't regress as new features are added.

What it also gives us is images of the testing in progress. We're presently using this with Playwright, which also enables us to get screenshots and videos of the flow. We do this via a testing model that enables this to take place.

The Process

Video: A walkthrough of the Codebots internal Auto Documentation Process

Here's how we do it. Firstly, we link the cross-model references from the Codebots target testing models and requirements models to the auto documentation 'acceptance' model. This enables us to keep them in parallel and ensure they're correctly updated. In the acceptance model, as per the example, we can either write what we want the documentation to be and link it to the required steps, or we can pull this from a testing and requirements model which form the intention of the application and user flow.

Once connected, we're able to use the models to auto-write the documentation and publish this to the Git Repo. What this means is that whenever a requirement or test is updated, we self-test to ensure it hasn't changed. If it has, we only need to update the model. This means we have validation between the requirement, tests, and the target documentation.

Once this is achieved 1 for 1, it becomes very easy to maintain these from the model. When the documentation repository is updated, we can use pipelines that publish this, in line with the target application to be published on a static site generator.

Not shown in the video, is the Codebots Knowledgebase, this is a static site available from within the platform that provides all user guides complete with always up to date text, video’s and images!

Image: The output of the Auto Documentation Process internal to the platform on a static site.

Conclusion

When it comes to the modernisation of legacy systems, this is an invaluable tool. The Codebots Auto Document Generation not only modernises the system but also saves countless hours of labour, making it a revolutionary approach to software documentation.