Documentation: from headache to streamlined process

At many organisations, creating and maintaining documentation is a headache. Documentation is often out of date or, worse still, missing entirely. There had to be a better way, we thought at JAM-IT. So we developed an approach that turns documentation into a streamlined process.

What makes documentation such a headache

Developers forget to update it

Updates are made and new features are added to the application all the time. But updating the documentation? That is often not part of the developer's process. In practice the organisation thinks, every once in a while: we really should update our documentation. And then everything gets brought up to date. The result: for a large part of the time the documentation is out of date.

For the users of the app it is a maze

This is roughly how the hunt for documentation goes in many apps:

• You have to leave the app and go to a separate documentation website
• There you have to look for what you need, through the search function or by digging through lists of articles
• Only to find out that the documentation is no longer correct
• And to contact customer service

Absolutely no fun as a user.

The solution? Documentation as an integral part of the application

At JAM-IT we have changed course. We no longer see documentation as a separate element, but as an integral part of our applications. How does that work in practice?

Help at the right moment, in the right place

Imagine: you are working in an application and need a bit of explanation. You click on a question mark next to the field you are working on and immediately see the relevant information. And you can carry on.

The result?

• Users find what they are looking for much faster
• The application is used better, because more people see the tips for using it
• Your customer service has less work, because users solve more themselves

Developers write and update the documentation inside the app

We have fully integrated writing documentation into the development process. Do developers change something in the app? Then they can change or add the documentation inside their development environment. So they no longer have to create the documentation separately on an external documentation site.

The result?

• Updating documentation becomes a natural part of the development process
• Creating and updating documentation is never forgotten again
• Developers save time because they do not have to switch between different systems

Updates in the app automatically lead to updates on the documentation site

For users it is sometimes still nice to have all the documentation in one place. That is why we still have a separate documentation website. But we have almost fully automated filling and updating that site. We have developed tools that automatically extract the in-app documentation and process it into the documentation site.

The benefits?

• The documentation site is always up to date with the latest version of the application
• No extra work is needed to update the documentation site
• Less chance of errors from manual updates

Example: how we do this within JamOps

In JamOps (our DevOps solution for Mendix) users can configure all sorts of things. Every configuration option has a tooltip to help the user on their way. The user sees this tooltip immediately when they click the question mark, and does not have to dig through all kinds of documentation first.

Does a user want an overview of all the documentation? No problem. All the tooltips can be found on the JamOps documentation site. They are loaded in automatically. And if a developer changes a tooltip in the application? Then the documentation site is automatically updated as well.

The same goes for explanations of rules. All sorts of rules are built into JamOps (they check the code) and the JamOps developers always write an explanation to go with them. That explanation is also loaded automatically onto the JamOps documentation site.

Documentation does not have to cause a headache

By integrating documentation into our development process and making use of automation, we have created a system that saves time, prevents errors and raises the quality of our documentation. The result? Happier developers and clients who can use the app better.

Want to know more about how we handle quality and documentation? Then also read our article about our ISO 27001 certification.