From monolithic to modular documentation

Three years ago, the SUSE documentation team embarked on a transformative journey, shifting from the traditional approach of creating large, monolithic user guides to developing topic-based, modular documentation – what we now call SUSE Smart Docs. This ambitious project has kept us actively engaged over the past few years, and we remain fully committed to its ongoing progress. In this article, we will delve into the rationale behind this strategic shift, the critical observations and decisions we encountered along the way, and the valuable insights we have gained from this initiative.

The documentation scope and team

SUSE, founded in 1992 in Germany, is a global leader in innovative, reliable, and secure enterprise open-source solutions. We believe that what sets SUSE apart is our active engagement and partnership with open-source communities worldwide, fostering a collaborative environment that drives continuous improvement and technological advancement.

Our small team of technical writers is responsible for creating the documentation for our core products, which collectively results in 68 guides. Most of these products follow an annual release cycle, and some are supported for up to 13 years, requiring extensive and ongoing maintenance of the documentation.

Figure 1: SUSE documentation scope and team
Source: SUSE

In addition, other teams contribute supplementary product documentation, adding 121 more guides to our portfolio. In total, we maintain 190 product manuals and guides, articles, best practices, and technical reference documents.

Our primary language is English, and the documentation is translated into up to 13 languages to ensure global accessibility and support.

Challenges of monolithic guides

Let us explore the structure and writing process of our monolithic user guides and the pain points that come along with it. As an example, we will use one of our largest user guides, the “SUSE Linux Enterprise Server Administration Guide”.

 This comprehensive guide spans 730 pages and addresses a mixed target audience, ranging from rookie desktop users to experienced system administrators. The guide is available for the SUSE Linux Enterprise product family. This product family consists of eight product variants and the Administration Guide is available for four of these product variants. Some of these product variants are supported for up to 13 years, which results in maintaining up to 16 variants of this guide.

The source files are written in DocBook XML and stored in Git for version control. One XML file usually covers a chapter or subchapter. In these files, text and graphics are marked to indicate which product variant they apply to.

Each guide has a main book XML file that controls which source XMLs will be taken to assemble the final guide. Then a documentation configuration file is applied to filter for the content that is valid for the selected product variant. To run profiling, apply filtering, and build the PDF or HTML output, we use a tool called DAPS (DocBook Authoring and Publishing Suite). DAPS is a complete environment for building HTML, PDF, EPUB, and other formats from DocBook XML. It is freely available at https://github.com/openSUSE/daps.

Figure 2: Profiling and build process
Source: SUSE

The final guides are then published to our documentation portal at documentation.suse.com.

Pain points for customers

Our ongoing customer analyses and surveys have revealed the following three main pain points for our users:

• The documentation does not meet search behavior requirements:
  Over 80% of our readers access our content through search engines, seeking answers to specific questions rather than navigating our documentation portal. This often means that they end up in the middle of a guide without the necessary context.
• The documentation carries too many redirects:
  The guides contain numerous links to other sources, sometimes creating a maze of redirects that disorient users.
• The documentation has a poor SEO ranking:
  Despite our Search Engine Optimization (SEO) efforts, and even though the SEO auditing tools gave us good ratings, our content was ranked very low in the search engine results.

Pain points for the documentation team

In addition to these customer pain points, the monolithic approach also creates challenges for our documentation team:

• Limited content reuse:
  The source files are stored in different repositories, making it difficult to share XMLs or text snippets between them.
• Maintenance effort:
  Maintaining a large guide can be very time-consuming, as any feature change requires updating the entire document.
• Limited collaboration:
  Each technical writer is responsible for an entire guide, limiting collaboration and work distribution.

SUSE Smart Docs: a modular approach

The challenges faced by our customers and our team highlighted the limitations of the monolithic approach and underscored the need for a more efficient and user-friendly documentation strategy. This realization led us to embark on the journey towards modular documentation, known as SUSE Smart Docs.

Changes in publication

Since most customers access our documentation through search engines, any page can be their first and only experience. Providing enough context per page is a challenge when writing texts linearly, like we do for the monolithic guides.

To address the customer pain points, we decided to split the content of the guides into smaller chunks (loosely based on previous chapters) and publish them as standalone articles. Each article addresses common tasks around a subject, including hands-on examples and troubleshooting. Thus, it provides all the information needed to solve a certain problem. “Don’t tell me how it works, tell me how to use it!” became our credo. As a result, readers can stay on the same page and do not need to follow cross-references to get the big picture. This way of presenting the information also enhances the findability on the Web, as shown in our proof of concept.

Changes in authoring

Along with the publication change, we also switched to topic-based authoring. This allows us to reuse pieces of information across the documentation for different product variants without the need to duplicate (source) content and risk the copies getting out of sync.

Each topic is an information unit that is self-contained, reusable in different contexts, and serves a distinct purpose. Topics are like building blocks that we assemble into articles (our so-called SUSE Smart Docs). Each topic can be reused in multiple articles.

Here is an example of how the topic-based approach helps us:

As stated above, our core products have an annual release cycle and long lifecycle, resulting in multiple product versions being on the market simultaneously. With topic-based authoring, we can now split version-specific information into separate articles (which share about 80-90% of their content). This reduces writing and maintenance effort while helping customers quickly find specific instructions that match their product version.

Proof of concept – proof of success

Before rolling out the SUSE Smart Docs on a bigger scale, we ran a proof of concept (PoC). After rewriting parts of our existing documentation, we subjected both variants (monolithic and modular) to an A/B test to see which one performed better.

Figure 3 shows one example from the PoC and highlights the major differences between the two variants:

Figure 5: Comparing monolithic to modular documentation
Source: SUSE

When comparing the Google Analytics data for both variants (collected over the same three-month period), the results far exceeded our expectations. While the chapter in the guide received 755 views (based on the product version with the highest overall documentation views), the two Smart Doc articles (covering roughly the same content as the chapter) received about 15 times more views – 11,105 views in total. The trends for the rest of the PoC were similar.

Figure 6:  Google Analytics results for proof of concept
Source: SUSE

We attributed this to the fact that articles allow for better fine-tuning of metadata (focusing on the concrete subject of the article), resulting in a higher search engine ranking.

Based on the results of the PoC, we got the final buy-in from our internal stakeholders to roll out the documentation for our upcoming product lines as SUSE Smart Docs. This means we now fully rely on topic-based authoring for those product lines.

Lessons learned

Our lessons learned included the following:

1. Get your team on board: Significant effort is required in training tech writers to rewrite content according to the new approach. At SUSE, it proved valuable to involve the team in decisions, where possible, and to provide continuous feedback on the results.
2. Get your stakeholders on board: Due diligence and providing data are key, starting with a problem analysis and an action plan. Continuously collect data to base decisions on and justify investment decisions.
3. Flexibility and adaptation: Initial decisions may need to be revised as the project progresses, and flexibility is crucial. Be prepared to learn as you go.
4. The big picture: Changing one thing may affect another thing, forcing you to prioritize and reschedule goals or milestones.
5. Consider your situation and resources: Evaluate your specific situation and trade off risks and benefits. Sometimes “One size does not fit all.”

Here are two examples of major decisions we took, highlighting the importance of lessons 3 to 5.

Focus on writing and publication

Had we focused solely on the content production and switched to topic-based authoring without thinking about the publication of the resulting deliverables, we would have missed an important issue: Splitting up the content of a single book into individual articles, multiplied by the number of books we maintain per product variant and product versions, would have left us with a myriad of articles that need to be published and findable on our documentation website. This led to a change of plan, ultimately resulting in the creation of a new documentation portal – with an enhanced user interface, navigation, filter option, and extended search capabilities. We decided to push forward the implementation of the major features of the documentation portal and to prioritize them over modular content creation.

Tools and processes

Looking at our specific situation as a company operating in an open-source environment, we soon realized that introducing a content management system and switching from DocBook to DITA would have cost us a lot of achievements we had reached in the past. The major thing to name here is fostering developer contributions to the documentation by using the “Docs as Code” approach. Therefore, our decisions were:

• to continue using Git for version management and review workflow
• to stick with our well-established and self-maintained open-source toolchain, the DocBook Authoring and Publishing Suite (DAPS)

To the latter, we added support for the creation and assembly of modular documentation, while at the same time sticking to DocBook XML. This also gives us greater flexibility because it still allows us to bundle articles into guides, should this be required. The combination of “Docs as Code” and our toolchain also supports the continuous release and translation of documentation.

Key benefits

We can report the following benefits of modular documentation that we have introduced as SUSE Smart Docs:

• Content reuse: Articles can be combined and topics can be reused in multiple articles, reducing redundancy and improving efficiency.
• Collaboration: Different maintainers can handle different topics, allowing for better work distribution and more efficient collaboration.
• Continuous release cycles: Updates can be made to specific articles or topics with no need to update an entire guide, making the process more efficient and agile.
• Improved findability and usability: Users are now directed to specific articles that answer their questions, reducing the need to navigate through large guides.
• Enhanced SEO: The modular approach has led to higher search engine rankings and more views for specific content, such as the sudo Smart Docs, which saw 15 times more views compared to the monolithic version.

Conclusion

The transition from monolithic to modular documentation has been a significant undertaking for the SUSE documentation team. While it has presented challenges, the benefits – including content reuse, collaboration, and continuous release cycles – have been substantial. By addressing the pain points experienced by both customers and the documentation team, we have improved the overall user experience and the efficiency of our documentation processes. The journey continues, and we remain committed to refining and enhancing our modular documentation approach.