Automated documentation testing with PlantUML and OpenAPI

Software documentation is an essential part of software development. It allows developers from different teams to make full use of each other's services. Unfortunately, that documentation is often difficult to keep in sync with the code. Our collaborator Mark Dechamps and his team searched for a way to automatically check if our internal documentation is still up to date, and found one.

Mark: At our customers, we use PlantUML to draw diagrams for our internal documentation on Confluence. This documentation describes the APIs of our services using flowcharts. As this documentation is very useful for communication between teams, it is crucial that the diagrams correctly show all details. If a parameter or another component has been changed, that should be reflected in the documentation as soon as possible.

Our solution consists of a kind of unit test that checks whether the documentation is still correct. We include a PlantUML file with our code, and run a test that requests the OpenAPI and compares it with the PlantUML diagram during the build. If those files do not match, the test fails and prompts an error message.

We wrote the project in TypeScript on Node.js. The project uses Purify, a library for functional programming with TypeScript. It was hard work, but at the end of the Innovation Day we already had a first working version that could detect missing nodes in the diagrams.

A CLI for React and React Native

If the term CLI does not ring any bells, you will probably still recognise it from hacking scenes in films or television series. A CLI or Command Line Interface is a usually black screen where users can enter commands to control a program or operating system. Our colleague Jos De Berdt explains the new CLI that his team developed for React and React Native.

Jos: On television CLIs are mostly there to look impressive and technically complicated, but they certainly have their uses in reality. A CLI makes it easier for us developers to manage and document a project. This leads to less development time, more consistency in code, and more accurate documentation.

We also chose Node.js to create our CLI. The CLI allows us to create files that use components, states and other functions in React and React Native quickly and easily. In addition, the interface installs the most frequently used modules and helps us when writing documentation. Because we connected the CLI to the project itself instead of a code editor, we can continue using our favourite shortcuts everywhere.

One of our pillars at Sweet Mustard is building an inspiring community, and this project truly shows our commitment. So, we have made the code for this CLI available to the entire Node.js community via the node packaging manager (NPM): https://www.npmjs.com/package/...

Automation of design systems

Developing and maintaining a design system often involves a great deal of manual work, like keeping examples up to date and aligning design tokens with both the design and code. If not all changes in design or code are implemented in the system, the gap between design and development could widen.

A design system is meant to bring those parties closer together instead of further apart, so the importance of synchronisation can hardly be underestimated. That’s why some of our developers decided to complete the circle between design, documentation and development by automating some of these aspects. Our colleague Ibe Vanmeenen explains how they bridged the gap.

Ibe: Our previous method was to export an image of a component from Figma, the program that we use for our designs. We then manually placed this component as an image in our design system. We also had to update this documentation manually if changes were made to the component’s implementation in the code.

Our new setup uses the Zeroheight programme and can connect to both Storybook (code) and Figma (design). Manual adjustments are now a thing of the past, as all changes are automatically synchronised. This means that there is much less maintenance work and manual documentation involved. Our solution helps us to take a pragmatic approach to developing and maintaining design systems, without the costs that people usually associate with them.

This year again, there were many interesting technical developments, by and for our employees. Would you like to help Sweet Mustard grow, work with the latest technologies and help your colleagues every day? Then be sure to contact us, because we are always looking for new enthusiasts!