This is the source of the official SUSE modular documentation. The repository currently covers the documentation for the SLE 16 product family, SUSE Linux Micro and SUSE AI.
For the above SUSE products we provide modular documentation, using topic-based authoring. This approach allows us to reuse pieces of information across articles (and across different product variants) without duplicating source content.
Our goal is to write task-based documentation that helps readers find a solution to their problem quickly. For this purpose, the documentation is split into a set of articles (so called 'Smart Docs').
Each article stands for itself. It minimally includes the following:
- requirements
- context
- instructions
- examples
- troubleshooting
- FAQs
Technically, Smart Doc articles are built from individual topics, like "building blocks". Each topic is an information unit that is
- self-contained,
- serves one distinct purpose (see the four topic types provided),
- can be reused in multiple articles.
According to their purpose, we dinstinguish between four topic types:
- Task: instructs (how to?)' - XML template
- Concept: explains (what is?) - XML template
- Reference: informs (e.g. list of options, table with config files, default settings) - XML template
- Glue: helps navigate (combines texts or structures that do not fit into any of the other categories): Typical glue topics are the "For more information" and the "What's next" sections. - XML template
Articles are built by bundling these topics into assembly files - organizational units that structure the topics. The assemblies are used to build coherent and meaningful documents XML template.
To build documents and validate assemblies, DAPS version 4.X Beta 11 and geekodoc are needed. To install the requried tools, proceed as follows:
-
Add the documentation zypper repository:
sudo zypper ar https://download.opensuse.org/repositories/Documentation:/Tools/ Documentaton:Tools -
Refresh your repositories:
sudo zypper ref -
Install daps and geekodoc:
sudo zypper in daps geekodoc
For a comprehensive list of conventions for modular docs, turn to the templates README.