Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/**
Expand Down
64 changes: 64 additions & 0 deletions docs/contributing/documentation_workflow.md
Original file line number Diff line number Diff line change
@@ -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
Loading