Joining the ALP experience: documentation goes modular

The following article has been contributed by Tanja Roth, Project Manager Technical Documentation at SUSE.

With the release of the Adaptable Linux Platform (ALP) prototype ‘Les Droites’ in September, the first Alpine summit of more than 4,000 meters has been reached. As the Adaptable Linux Platform is a shift towards a modular operating system, what would be more natural than to accompany it with modular documentation? Since the initial publication of the ‘SUSE Smart Docs’ pilot last year, which is based on this approach, the collection of articles on the ‘Smart Docs’ beta documentation page has grown.

Modular documentation

Now – in parallel with ALP development breaking new ground – for the first time the SUSE documentation team applied modular writing principles to a larger amount of documentation (which we mostly had to create from scratch). The content was broken down into brief self-contained units which fulfilled a specific purpose. Each unit provides either of the following:

• Step-by-step procedure

Current example: Enabling Podman
https://documentation.suse.com/alp/all/html/alp/concept-containers-podman.html#task-enable-podman

• Explanation of a concept

Current example: Concepts of the Adaptable Linux Platform
https://documentation.suse.com/alp/all/html/alp/concept-alp.html

• Reference

Current example: Available workloads for the Adaptable Linux Platform
https://documentation.suse.com/alp/all/html/alp/concept-alp.html#reference-available-alp-workloads

Higher flexibility

At first sight, the recently published ALP documentation does not look much different from our SUSE Linux Enterprise documentation.

This is because for the first ALP prototype, we have bundled those content units into a bigger entity – and published them as ALP Guide. But this is part of the flexibility of this new approach:

From the content building blocks in the back-end, we still have the possibility to publish a consecutive piece of documentation at the front-end. At the same time, the modular writing approach allows us to assemble the building blocks in multiple ways and to reuse them within different contexts – similar to a LEGO building kit.

Reaching the next peaks

So for now, the major changes are mainly ‘under the hood’. They consisted primarily of applying the modular writing principles on a bigger scale. And we have adjusted the documentation infrastructure to provide more flexibility for the future documentation approach. But there is much more to come. Stay tuned for more visible changes with the next ALP prototypes!