This repository contains modular documentation for SUSE products. The documentation consists of smaller information units with the following characteristics:
-
Self-contained
Including requirements, context, instructions, and FAQs. Each information unit is supposed to stand for itself.
-
Cover one distinct purpose:
Rather than covering a complete technology or a set of problems, each information unit covers only one distinct topic. We provide three different types of information units:
- Task (how to?) - XML template
- Concept (what is?) - XML template
- Reference (e.g. list of options, table with config files, default settings) - XML template
-
For re-use in different contexts:
Every information units stands for itself, but it can be bundled into collections that cover different products/solutions.
- use hyphens as separators
- use type as prefix (task-|concept-|reference-)
- content must be obvious from filename
- example: topic-register-product-after-installation.xml
- use hyphens as separators
- content must be obvious from filename
- example: yast2-register-sles.png
- use hyphens as separators
- root ID:
- use type as prefix (task-|concept-|reference-)
- for task type, use verb in infinitive: e.g. task-register-product-after-installation
- for concept/reference type, use nouns: e.g. reference-zypper-options, concept-fencing
- section IDs: must not reflect structure
- one DC file per information unit
- should match root ID of file
- add the following metadata as comment at the top of a file:
- productname (e.g. SLES) - can be multiple
- product version (e.g. 15 SP3) - can be multiple
- topic category/ies (see below Categories) - can be multiple
- target group(s) - can be multiple
- initially published
- last modified
Each information unit should be marked as belonging to one or more of the following categories:
- architecture
- planning
- installation
- deployment
- upgrade
- system administration
- network
- tuning
- security
- public cloud
- storage
- container
- virtualization