Maintaining our documentation up-to-date

We maintain an up-to-date documentation for your editors' convenience, and we are the only Drupal distribution to do so. And even in German.

Each website is different, and most web development companies develop highly customized solutions and both standard components of the CMS and the customisation evolve quickly. This means that for these companies - and the customers - it is unaffordable to write and maintain up-to-date documentation targeted to the editors.

The severity of the conflict and pain in documentation leads to odd dogmas including “Working software over comprehensive documentation” from the Agile Manifesto. Documentation is thus too often mostly skipped in agile projects.

Editors are thus left alone and onboarding of new parties is extensive, leading to additional cost due to many support requests and training of new editors.

This project aims to simplify and automate the process of maintaining Primer documentation to provide customers with up-to-date and helpful documentation, thus easing the website-editing process, and reducing costs linked to support.

The structure of the software user interface and the documentation is designed to apply similarly to projects with varying levels of customizations.

In addition, up-to-date documentation proves the simplicity of solving common requirements for potential new customers during the offering phase.

We developed a tool allowing us to automatically generate and update the documentation screenshots. This way, we can continuously improve the user experience of our product without losing the benefit of up-to-date documentation screenshots.

Automatically creating screenshots also has side benefits:

• Multilingual documentation screenshots can be performed in just one variable change
• User role and permissions in a screenshot can be easily customized to control visible elements
• Developers can participate. Because the screenshots are generated by scripting instead of manually, the developers can easily write scripts to document the processes they develop.
• As a nice side effect, regressions in the admin user interface can be easily identified.

So far we generated more than 500 screenshots that have been regenerated multiple iterations and do not need to be dealt with any further, and we can now afford to document the less used features.

It is in addition possible to zoom-in on each screenshot and access the screenshot of the full screen, allowing you to rapidly find where on the screen is the region of interest, if needed.

This method depends on 2 main blocks: generating the screenshots, and updating them on the website.

The first step - automatically generating the screenshots - is performed benefiting from the test-framework Behat. We already used Behat for our automated tests checking that the website behaves as expected, but Behat can also be used to generate screenshots.

In our case, we work with this framework to create meaningful screenshots. We also use it to add css elements such as highlights, numbers, etc. 

This way, cosmetic and contextual changes of the documented pages are automatically taken into account and the highlights are always at the right place.

The second step of this process is to seamlessly but not blindly update the screenshots. Indeed, we don’t want to have to check every single new screenshot, especially if they are completely identical, but we don’t want to miss any unwanted change either.

We first created a specific media type. This media type contains the current screenshot with everything linked to it such as the uncropped version of the screenshot and any other important information (language, required user status, etc). It can also hold a second, updated version of the screenshot.

An automated script is used to fill this second field with the new screenshot, if it is different from the current one. Thus, only screenshots that actually changed are ‘to be checked’.

When the screenshot does change, we can review it and decide whether we want the former screenshot replaced or not. A nice side-effect is that we can also very easily spot unwanted behavior in our platform and rapidly correct it.

We can then simply validate the change on the review screen and the screenshots in the website are automatically updated.

Primer is built from components, common to all projects. All customers share the same back end platform, which allows us to afford to develop and maintain useful documentation. 

In turn, this makes our solution the only Drupal distribution offering such documentation.