Skip to content

Commit bbfbaaa

Browse files
committed
Docs: Create Documentation Workflow
1 parent 162d7de commit bbfbaaa

2 files changed

Lines changed: 66 additions & 1 deletion

File tree

.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,10 @@ shell.nix
99
# added by aggregation
1010
docs/projects
1111

12-
# Section directories - aggregated content is ignored, index.md is tracked
12+
# Section directories - aggregated content is ignored, index.md and selected files are tracked
1313
docs/contributing/**
1414
!docs/contributing/index.md
15+
!docs/contributing/documentation_workflow.md
1516
docs/explanation/**
1617
!docs/explanation/index.md
1718
docs/how-to/**
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
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

Comments
 (0)