From 0b6f3cfd269011fa7ffafe0d4a650572a8863c4f Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Tue, 31 Mar 2026 18:00:44 +0200 Subject: [PATCH] Docs: Create Documentation Workflow --- .gitignore | 3 +- docs/contributing/documentation_workflow.md | 64 +++++++++++++++++++++ 2 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 docs/contributing/documentation_workflow.md diff --git a/.gitignore b/.gitignore index f399ac6..db6a6e8 100644 --- a/.gitignore +++ b/.gitignore @@ -9,9 +9,10 @@ shell.nix # added by aggregation docs/projects -# Section directories - aggregated content is ignored, index.md is tracked +# Section directories - aggregated content is ignored, index.md and selected files are tracked docs/contributing/** !docs/contributing/index.md +!docs/contributing/documentation_workflow.md docs/explanation/** !docs/explanation/index.md docs/how-to/** diff --git a/docs/contributing/documentation_workflow.md b/docs/contributing/documentation_workflow.md new file mode 100644 index 0000000..9b6bf5d --- /dev/null +++ b/docs/contributing/documentation_workflow.md @@ -0,0 +1,64 @@ +--- +title: Documentation Workflow +description: How to contribute Documentation to Gardenlinux +order: 1 +--- + +# Documenting Gardenlinux + +This guide will provide you a detailed overview over everything you need to know +to support our efforts in documenting the Gardenlinux project. + +## When Is Documentation Necessary? + +Documentation is always necessary when a piece of software, a process or +information is touched that has implications for other people. May they be +internal or external contributors, users or decision makers. + +## What Should Be Documented? + +In the context of this Documenation Hub, anything that has implication to the +"outside". Meaning other users, operators, developers or decision makers needs +to be documented accordingly. + +This includes but is not limited to: + +- Usage of Gardenlinux and any supporting tool +- Features and components of the project +- Ways to contribute and where to find help +- Information about where to submit security incidents +- Information about who is developing the project + +Of course this does not apply to purely internal changes like code cleanup +contributions or similar that have no outside effect. + +## Who Is Responsible for Maintaining Documentation? + +The question of _"who is responsible?"_ can be split into two camps: The +contributors and a documentation lead. + +### Contributors + +Contributors are defined as individuals, groups or organisation that submit code +or non-code contributions to the project. These should, in addition to their +submition, document their changes with appropriate changes to any relevant +pieces of documentation. This applies to _any contribution_ if the change is +relevant for others. + +For example: + +1. A person introduces a new feature to Gardenlinux and opens a Pull Request +2. After their PR is approved, they are greenlit to open a PR in the `docs-ng` + branch of the code repository in which they document their new feature. +3. The PR will be reviewed by a maintainer or the documentation lead on duty. +4. After both are greenlit, both PRs are merged. + +### The Documentation Lead + +This is a more or less informal position that is quite common in many projects: +One maintainer/developer who is responsible for handling the documentation hub +and enforcing style and quality standards according to written design documents. + +## The Review Process + +## Quality Markers