Joining the ALP experience: documentation goes modular | SUSE Communities

Joining the ALP experience: documentation goes modular

Share
Share

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 Podmanhttps://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 Platformhttps://documentation.suse.com/alp/all/html/alp/concept-alp.html

  • Reference

Current example: Available workloads for the Adaptable Linux Platformhttps://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!

Share
(Visited 1 times, 1 visits today)
852 views
Meike ChabowskiMeike Chabowski works as Documentation Strategist at SUSE. Before joining the SUSE Documentation team, she was Product Marketing Manager for Enterprise Linux Servers at SUSE, with a focus on Linux for Mainframes, Linux in Retail, and High Performance Computing. Prior to joining SUSE more than 20 years ago, Meike held marketing positions with several IT companies like defacto and Siemens, and was working as Assistant Professor for Mass Media. Meike holds a Master of Arts in Science of Mass Media and Theatre, as well as a Master of Arts in Education from University of Erlangen-Nuremberg/ Germany, and in Italian Literature and Language from University of Parma/Italy.