|
| 1 | +--- |
| 2 | +title: Documentation Workflow |
| 3 | +description: How to contribute Documentation to Gardenlinux |
| 4 | +order: 1 |
| 5 | +--- |
| 6 | + |
| 7 | +# Documenting Gardenlinux |
| 8 | + |
| 9 | +This guide will provide you a detailed overview over everything you need to know |
| 10 | +to support our efforts in documenting the Gardenlinux project. |
| 11 | + |
| 12 | +## When Is Documentation Necessary? |
| 13 | + |
| 14 | +Documentation is always necessary when a piece of software, a process or |
| 15 | +information is touched that has implications for other people. May they be |
| 16 | +internal or external contributors, users or decision makers. |
| 17 | + |
| 18 | +## What Should Be Documented? |
| 19 | + |
| 20 | +In the context of this Documenation Hub, anything that has implication to the |
| 21 | +"outside". Meaning other users, operators, developers or decision makers needs |
| 22 | +to be documented accordingly. |
| 23 | + |
| 24 | +This includes but is not limited to: |
| 25 | + |
| 26 | +- Usage of Gardenlinux and any supporting tool |
| 27 | +- Features and components of the project |
| 28 | +- Ways to contribute and where to find help |
| 29 | +- Information about where to submit security incidents |
| 30 | +- Information about who is developing the project |
| 31 | + |
| 32 | +Of course this does not apply to purely internal changes like code cleanup |
| 33 | +contributions or similar that have no outside effect. |
| 34 | + |
| 35 | +## Who Is Responsible for Maintaining Documentation? |
| 36 | + |
| 37 | +The question of _"who is responsible?"_ can be split into two camps: The |
| 38 | +contributors and a documentation lead. |
| 39 | + |
| 40 | +### Contributors |
| 41 | + |
| 42 | +Contributors are defined as individuals, groups or organisation that submit code |
| 43 | +or non-code contributions to the project. These should, in addition to their |
| 44 | +submition, document their changes with appropriate changes to any relevant |
| 45 | +pieces of documentation. This applies to _any contribution_ if the change is |
| 46 | +relevant for others. |
| 47 | + |
| 48 | +For example: |
| 49 | + |
| 50 | +1. A person introduces a new feature to Gardenlinux and opens a Pull Request |
| 51 | +2. After their PR is approved, they are greenlit to open a PR in the `docs-ng` |
| 52 | + branch of the code repository in which they document their new feature. |
| 53 | +3. The PR will be reviewed by a maintainer or the documentation lead on duty. |
| 54 | +4. After both are greenlit, both PRs are merged. |
| 55 | + |
| 56 | +### The Documentation Lead |
| 57 | + |
| 58 | +This is a more or less informal position that is quite common in many projects: |
| 59 | +One maintainer/developer who is responsible for handling the documentation hub |
| 60 | +and enforcing style and quality standards according to written design documents. |
| 61 | + |
| 62 | +## The Review Process |
| 63 | + |
| 64 | +## Quality Markers |
0 commit comments