From 9eb9bb0ec94b871f28576400ce933fb7535fb7e7 Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Tue, 31 Mar 2026 18:00:44 +0200 Subject: [PATCH 1/5] Docs: Create Documentation Workflow --- .gitignore | 3 +- docs/contributing/documentation_workflow.md | 127 ++++++++++++++++++++ 2 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 docs/contributing/documentation_workflow.md diff --git a/.gitignore b/.gitignore index e1c6a07..9335d39 100644 --- a/.gitignore +++ b/.gitignore @@ -12,11 +12,12 @@ docs/**/.media docs/**/_static docs/**/assets -# 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/ !docs/contributing/documentation/** +!docs/contributing/documentation_workflow.md docs/explanation/** !docs/explanation/index.md !docs/explanation/documentation/ diff --git a/docs/contributing/documentation_workflow.md b/docs/contributing/documentation_workflow.md new file mode 100644 index 0000000..cb1948d --- /dev/null +++ b/docs/contributing/documentation_workflow.md @@ -0,0 +1,127 @@ +--- +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 Documentation 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 +submission, 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. + +This can be a liaison to a formal documentation team who is briefed on the +project and works closely with the development team, a team member that is +permanently appointed to or volunteers for this position, or a rotating position +that anyone in the team may take on for a set amount of time. + +However this may be implemented it is important to stress that _**documentation +is a team effort**_. + +The responsibilities of this person are: + +- Evaluating whether a contribution requires documentation & what scope that + documentation needs to be +- Making sure that documentation is written and put in the correct space +- Ensuring that the documentation pipeline is running and the documentation + website is accessible + +## The Review Process + +Any changes to documentation will be reviewed by maintainers for the quality +criteria mentioned below. Only after the review is sucessful will the changes be +merged. The review validates: + +- **Technical accuracy and sufficient depth**: The document matches implemented + behaviour and guides are executable. +- **Completeness**: All affected changes are documented. +- **Readability**: The documentation is free of typos and grammatical errors. +- **Style and Inclusivity**: Language follows the project's expectations and + quality criteria, all images have appropriate alt text descriptions for people + using screen readers. + +In cases where there is a Documentation Lead, this person must review changes to +documentation for their adherence to the project's quality markers. + +In cases where there is **no** dedicated Documentation Lead, documentation +changes must be reviewed by other team members and tweaked according to their +feedback until unanimous agreement is reached. + +## Quality Markers + +All documentation should have a professional and inclusive tone. Gender-neutral +language (like they/them or role based nouns like "maintainer", "developer" or +"user") should be used. Language specific idioms common amongst native speakers +should be avoided and project specific abbreviations should always link to their +respective Glossar section. + +Documentation should go into appropriate detail for the intended autience (i.e. +Users or Developers) and not omit any details or become vague when talking about +specific topics. + +If a feature is not yet implemented or there are currently known bugs or Issues, +a "Known Issues" section should be appended to the bottom of the document +listing these issues and their corresponding GitHub issue if applicable. + +Include expected output or other steps which the reader can use to verify +operation outcomes in any instructional guides. + +Use examples liberally across the documentation for any document that advises +readers to action. + +## Version Compatibility + +Features that only apply to a specific versions of gardenlinux or supporting +tools should be marked as such using admonishments. + +Breaking changes between version should be indicated in a appropriately colored +warning or info box at the top of the document. From fcac6fc0c0a80fbd1ed7ff1fbf72d1b47209076a Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Wed, 8 Apr 2026 10:54:37 +0200 Subject: [PATCH 2/5] Docs: Remove mentions of the docs-ng branches & fix typos Signed-off-by: Tiara Lena Hock --- docs/contributing/documentation_workflow.md | 34 +++++++++++---------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/contributing/documentation_workflow.md b/docs/contributing/documentation_workflow.md index cb1948d..3b23260 100644 --- a/docs/contributing/documentation_workflow.md +++ b/docs/contributing/documentation_workflow.md @@ -34,24 +34,26 @@ 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 +The question of _"who is responsible?"_ can be split into two roles: 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 -submission, document their changes with appropriate changes to any relevant -pieces of documentation. This applies to _any contribution_ if the change is -relevant for others. +Contributors are defined as individuals, groups or organisations that submit +code or non-code contributions to the project. These should, in addition to +their submission, 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. +2. A maintainer reviews said feature and advises the contributor to write + documentation for it +3. Said documentation will reviewed by the maintainer in question or the + documentation lead if applicable +4. If both the code and the documentation both fulfill their respective quality + markers, the PR is merged ### The Documentation Lead @@ -71,15 +73,15 @@ The responsibilities of this person are: - Evaluating whether a contribution requires documentation & what scope that documentation needs to be -- Making sure that documentation is written and put in the correct space +- Making sure that documentation is written and put in the correct place - Ensuring that the documentation pipeline is running and the documentation website is accessible ## The Review Process Any changes to documentation will be reviewed by maintainers for the quality -criteria mentioned below. Only after the review is sucessful will the changes be -merged. The review validates: +criteria mentioned below. Only after the review is successful will the changes +be merged. The review validates: - **Technical accuracy and sufficient depth**: The document matches implemented behaviour and guides are executable. @@ -102,9 +104,9 @@ All documentation should have a professional and inclusive tone. Gender-neutral language (like they/them or role based nouns like "maintainer", "developer" or "user") should be used. Language specific idioms common amongst native speakers should be avoided and project specific abbreviations should always link to their -respective Glossar section. +respective Glossary section. -Documentation should go into appropriate detail for the intended autience (i.e. +Documentation should go into appropriate detail for the intended audience (i.e. Users or Developers) and not omit any details or become vague when talking about specific topics. @@ -120,7 +122,7 @@ readers to action. ## Version Compatibility -Features that only apply to a specific versions of gardenlinux or supporting +Features that only apply to a specific versions of Gardenlinux or supporting tools should be marked as such using admonishments. Breaking changes between version should be indicated in a appropriately colored From 05ec22828c768995345e513c1d4d650307edd5ef Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Wed, 8 Apr 2026 15:04:57 +0200 Subject: [PATCH 3/5] Docs: Add separate quality markers and finish doc workflow Signed-off-by: Tiara Lena Hock --- .../documentation_workflow.md | 96 ++++----- docs/contributing/documentation/index.md | 21 +- .../documentation/writing_good_docs.md | 185 ++++++++++++++++++ 3 files changed, 256 insertions(+), 46 deletions(-) rename docs/contributing/{ => documentation}/documentation_workflow.md (57%) mode change 120000 => 100644 docs/contributing/documentation/index.md create mode 100644 docs/contributing/documentation/writing_good_docs.md diff --git a/docs/contributing/documentation_workflow.md b/docs/contributing/documentation/documentation_workflow.md similarity index 57% rename from docs/contributing/documentation_workflow.md rename to docs/contributing/documentation/documentation_workflow.md index 3b23260..136b15b 100644 --- a/docs/contributing/documentation_workflow.md +++ b/docs/contributing/documentation/documentation_workflow.md @@ -6,8 +6,12 @@ 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. +This guide will provide you with a detailed overview over everything you need to +know to support our efforts in documenting the Gardenlinux project. + +If you would like to know what markers we use to determine if submitted +documentation is good, please check our guide about +[Document Quality Markers](./writing_good_docs.md) ## When Is Documentation Necessary? @@ -50,16 +54,16 @@ For example: 1. A person introduces a new feature to Gardenlinux and opens a Pull Request 2. A maintainer reviews said feature and advises the contributor to write documentation for it -3. Said documentation will reviewed by the maintainer in question or the +3. Said documentation will be reviewed by the maintainer in question or the documentation lead if applicable -4. If both the code and the documentation both fulfill their respective quality - markers, the PR is merged +4. If both the code and the documentation fulfill their respective + [quality markers](./writing_good_docs.md), the PR is 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. +and enforcing [quality standards](./writing_good_docs.md). This can be a liaison to a formal documentation team who is briefed on the project and works closely with the development team, a team member that is @@ -77,53 +81,55 @@ The responsibilities of this person are: - Ensuring that the documentation pipeline is running and the documentation website is accessible -## The Review Process +### Documentation Ownership -Any changes to documentation will be reviewed by maintainers for the quality -criteria mentioned below. Only after the review is successful will the changes -be merged. The review validates: +Documentation ownership depends on the scope: -- **Technical accuracy and sufficient depth**: The document matches implemented - behaviour and guides are executable. -- **Completeness**: All affected changes are documented. -- **Readability**: The documentation is free of typos and grammatical errors. -- **Style and Inclusivity**: Language follows the project's expectations and - quality criteria, all images have appropriate alt text descriptions for people - using screen readers. +- **Subproject documentation** (e.g., builder, python-gardenlinux-lib): Owned + and maintained by the contributors most active on that subproject if no formal + assignment to said project exist +- **Documentation hub content** (e.g., these contributing guides): Owned by the + Documentation Lead if that role exists, otherwise by the core team + collectively -In cases where there is a Documentation Lead, this person must review changes to -documentation for their adherence to the project's quality markers. - -In cases where there is **no** dedicated Documentation Lead, documentation -changes must be reviewed by other team members and tweaked according to their -feedback until unanimous agreement is reached. +## How to Submit Documentation Changes -## Quality Markers +To contribute documentation to Gardenlinux: -All documentation should have a professional and inclusive tone. Gender-neutral -language (like they/them or role based nouns like "maintainer", "developer" or -"user") should be used. Language specific idioms common amongst native speakers -should be avoided and project specific abbreviations should always link to their -respective Glossary section. +1. **Create a branch** named descriptively ideally with a `docs/` prefix +2. **Make your changes** following the [quality markers](./writing_good_docs.md) +3. **Add frontmatter** to your markdown files according to the + [technical reference](/reference/documentation/technical.md) +4. **Test your changes** locally by running the documentation server +5. **Open a Pull Request** with: + - Clear description of what documentation was added/changed + - Reference to any related code changes or issues + - Screenshots if visual changes were made +6. **Address review feedback** from maintainers or the Documentation Lead -Documentation should go into appropriate detail for the intended audience (i.e. -Users or Developers) and not omit any details or become vague when talking about -specific topics. - -If a feature is not yet implemented or there are currently known bugs or Issues, -a "Known Issues" section should be appended to the bottom of the document -listing these issues and their corresponding GitHub issue if applicable. +## The Review Process -Include expected output or other steps which the reader can use to verify -operation outcomes in any instructional guides. +Any changes to documentation will be reviewed by maintainers for the criteria +listed in the [quality criteria guide](./writing_good_docs.md). Only after the +review is successful will the changes be merged. -Use examples liberally across the documentation for any document that advises -readers to action. +In cases where there is a Documentation Lead, this person must review changes to +documentation for their adherence to the project's quality markers. -## Version Compatibility +In cases where there is **no** dedicated Documentation Lead, documentation +changes must be reviewed by other team members and tweaked according to their +feedback until unanimous agreement is reached. -Features that only apply to a specific versions of Gardenlinux or supporting -tools should be marked as such using admonishments. +The review validates: -Breaking changes between version should be indicated in a appropriately colored -warning or info box at the top of the document. +- **Technical accuracy and sufficient depth**: The document matches implemented + behaviour, commands are correct and tested +- **Completeness**: All affected changes are documented, prerequisites are + stated, next steps are provided +- **Readability**: The documentation is free of typos and grammatical errors, + has clear structure and flows logically +- **Style and Inclusivity**: Language follows the project's + [quality criteria](./writing_good_docs.md), all images have appropriate alt + text descriptions +- **Maintainability**: Documentation follows single source of truth principle, + ownership is clear, no unnecessary duplication diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md deleted file mode 120000 index aa5f121..0000000 --- a/docs/contributing/documentation/index.md +++ /dev/null @@ -1 +0,0 @@ -../../tutorials/documentation/index.md \ No newline at end of file diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md new file mode 100644 index 0000000..3c82c46 --- /dev/null +++ b/docs/contributing/documentation/index.md @@ -0,0 +1,20 @@ +--- +title: Documentation +description: Everything You Need to Know about Documenting Gardenlinux +order: 3 +--- + +# Documentation + +This section will tell you how to contribute documentation to Gardenlinux and +its associated projects and what metrics we use to assess whether documentation +is good. + + + +## References + +If you need to learn more about how to structure your documentation submission +from a aggregated repository like `gardenlinux`, `builder` or +`python-gardenlinux-lib`, please refer to the +[documentation references](/reference/documentation/technical.md). diff --git a/docs/contributing/documentation/writing_good_docs.md b/docs/contributing/documentation/writing_good_docs.md new file mode 100644 index 0000000..ba58a3b --- /dev/null +++ b/docs/contributing/documentation/writing_good_docs.md @@ -0,0 +1,185 @@ +--- +title: Documentation Quality Markers +description: Writing Good Documentation +order: 2 +--- + +# Documentation Quality Markers + +Good documentation should follow concrete and actionable quality markers to be +as helpful and professional as possible. + +These markers can roughly be split into required markers, that every +documentation submission should have, and those which are context dependent and +therefore optional. + +## Required Markers + +### Accuracy & Completeness + +It should go without saying that all documentation should be correct in an +informational sense. Meaning all code and commands need to be tested and any +tutorials & guides that are meant to lead a user through a process should be +executed by the reviewer once to see if they do what they were written for. + +All code examples should: + +- Be tested and verified to work +- Include expected output +- Cover common error cases where applicable +- Use realistic, representative examples + +All documents should cover all the aspects of their respective topics and not +exclude edge cases even if they appear infrequent. + +Each document should clearly state: + +- Prerequisites (required knowledge, tools, or setup) +- Context (when and why this information is relevant) +- Next steps or related documentation + +### Readability + +One of the most important factors of good documentation is readability. This +means that good documents should have a clear structure separated by concise +headlines that serves both as a navigation aid and a red string through the +topic. + +Another aspect of good readability is a well thought out **separation of +thoughts**. Ideally, every thought should have its own paragraph. This goes hand +in hand with keeping the sentence structure as short as possible and avoid +overly complex or nested sentences if possible. + +Additional readability guidelines: + +- Use active voice over passive voice +- Keep sentences focused (aim for 15-25 words) +- Use progressive disclosure (introduce simple concepts before complex ones) +- Break up long procedures into numbered steps + +### Style & Language + +All documentation should have a professional and inclusive tone. Gender-neutral +language (like they/them or role based nouns like "maintainer", "developer" or +"user") should be used. Language specific idioms common amongst native speakers +should be avoided and project specific abbreviations should always link to their +respective Glossary section. + +Hand in hand with the last point goes formulating documents with **consistent +terminology**. To avoid confusion, especially in tutorials, certain terms like +"install" and "set up" should not be used as synonyms, but instead have their +own respective meanings. + +Documentation should go into appropriate detail for the intended audience (i.e. +Users or Developers) and not omit any details or become vague when talking about +specific topics. + +If a feature is not yet implemented or there are currently known bugs or Issues, +a "Known Issues" section should be appended to the bottom of the document +listing these issues and their corresponding GitHub issue if applicable. + +Include expected output or other steps which the reader can use to verify +operation outcomes in any instructional guides. + +Use examples liberally across the documentation for any document that advises +readers to action. + +### Usability & Accessibility + +Every person browsing documentation has different means and needs. Not only in +the information they are looking for, but also how they access and process this +documentation. Language barriers or disabilities may present barriers when +attempting to look for something in documentation. + +There are a few things contributors can do to lower these barriers: + +- Use descriptive link texts instead of a simple "click here" +- Images should have a descriptive alt text that explains what the image shows +- Headings should have a proper hierarchy to ease browsing (don't skip heading + levels) +- Code examples should have syntax highlighting +- Navigation via keyboard must be possible across the site, the search bar + should ideally be accessible via key combination +- In graphs and other visual media, **color alone must never be the only + indicator of differences or importance** - use icons, labels, or patterns as + well +- All links should be verified as working (no dead links) +- Links to external resources should specify version where applicable + +### Discoverability + +The best documentation is useless if no one can find it. All documents must be +discoverable on all index pages or navigation bars and be linked in the +appropriate context. + +Documents should: + +- Have clear, descriptive titles +- Be placed in the appropriate section (Tutorial, How-to, Explanation, + Reference) +- Be cross-referenced from related documentation +- Include relevant keywords for search + +### Maintainability + +Documentation should be structured to minimize maintenance burden: + +- Follow the "single source of truth" principle; don't duplicate information + across multiple pages +- Include version information where relevant +- Clearly indicate ownership: + - For subproject documentation, the maintainers of that subproject + (identifiable via git blame) are responsible for updates + - For documentation hub content (like these guides), the Documentation Lead + owns maintenance if that role exists +- Use includes or references for content that appears in multiple places + +## Conditional Markers + +### Version Compatibility + +Features that only apply to specific versions of Gardenlinux or supporting tools +should be marked as such using markdown admonishments or any other suitable +formatting to make them stand out. + +Breaking changes between versions should be indicated in an appropriately +colored warning or info box at the top of the document. + +Version-specific content should include: + +- Minimum version required +- Version where feature was introduced +- Deprecation warnings if applicable + +## Checklist + +Use this checklist when reviewing or submitting documentation: + +### Core Markers + +- [ ] All code and commands are tested and working +- [ ] Prerequisites are clearly stated +- [ ] Expected output is shown for verification steps +- [ ] Document has clear structure with descriptive headings +- [ ] One main idea per paragraph +- [ ] Sentences are concise and use active voice +- [ ] Neutral and professional language throughout +- [ ] Gender-neutral language used +- [ ] Consistent terminology (no synonym confusion) +- [ ] Project-specific abbreviations link to Glossary +- [ ] All images have descriptive alt text +- [ ] Links use descriptive text (not "click here") +- [ ] Proper heading hierarchy maintained +- [ ] Code examples have syntax highlighting +- [ ] Color is not the only indicator in visual media +- [ ] All links verified as working +- [ ] Document is discoverable via navigation/index +- [ ] Cross-referenced from related documentation +- [ ] Clear ownership indicated + +### Conditional Markers + +- [ ] Version compatibility noted (if applicable) +- [ ] Breaking changes highlighted (if applicable) +- [ ] Known issues section included (if applicable) +- [ ] External dependencies documented (if applicable) From 35dd5bb1b7be74a03cb320a0ba610d7d603b5e2d Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Thu, 9 Apr 2026 08:17:28 +0200 Subject: [PATCH 4/5] Docs: Fix wording and add next steps sections Signed-off-by: Tiara Lena Hock --- .../documentation/documentation_workflow.md | 20 +++++++++++++------ docs/contributing/documentation/index.md | 4 ++-- .../documentation/writing_good_docs.md | 14 ++++++++++--- 3 files changed, 27 insertions(+), 11 deletions(-) diff --git a/docs/contributing/documentation/documentation_workflow.md b/docs/contributing/documentation/documentation_workflow.md index 136b15b..828e878 100644 --- a/docs/contributing/documentation/documentation_workflow.md +++ b/docs/contributing/documentation/documentation_workflow.md @@ -1,13 +1,13 @@ --- title: Documentation Workflow -description: How to Contribute Documentation to Gardenlinux +description: How to Contribute Documentation to Garden Linux order: 1 --- -# Documenting Gardenlinux +# Documenting Garden Linux This guide will provide you with a detailed overview over everything you need to -know to support our efforts in documenting the Gardenlinux project. +know to support our efforts in documenting the Garden Linux project. If you would like to know what markers we use to determine if submitted documentation is good, please check our guide about @@ -27,7 +27,7 @@ to be documented accordingly. This includes, but is not limited to: -- Usage of Gardenlinux and any supporting tool +- Usage of Garden Linux 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 @@ -51,7 +51,7 @@ change is relevant for others. For example: -1. A person introduces a new feature to Gardenlinux and opens a Pull Request +1. A person introduces a new feature to Garden Linux and opens a Pull Request 2. A maintainer reviews said feature and advises the contributor to write documentation for it 3. Said documentation will be reviewed by the maintainer in question or the @@ -94,7 +94,7 @@ Documentation ownership depends on the scope: ## How to Submit Documentation Changes -To contribute documentation to Gardenlinux: +To contribute documentation to Garden Linux: 1. **Create a branch** named descriptively ideally with a `docs/` prefix 2. **Make your changes** following the [quality markers](./writing_good_docs.md) @@ -133,3 +133,11 @@ The review validates: text descriptions - **Maintainability**: Documentation follows single source of truth principle, ownership is clear, no unnecessary duplication + +## Next Steps + +Before you get started, you might want to check out the following docs: + +- [Documentation Quality Markers](./writing_good_docs.md) +- [How to Documentation - Adding Repos to This Hub](/how-to/documentation/adding-repos.md) +- [How to Documentation - Working With the Aggregator Locally](/how-to/documentation/working-locally.md) diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md index 3c82c46..60ab286 100644 --- a/docs/contributing/documentation/index.md +++ b/docs/contributing/documentation/index.md @@ -1,12 +1,12 @@ --- title: Documentation -description: Everything You Need to Know about Documenting Gardenlinux +description: Everything You Need to Know about Documenting Garde Linux order: 3 --- # Documentation -This section will tell you how to contribute documentation to Gardenlinux and +This section will tell you how to contribute documentation to Garden Linux and its associated projects and what metrics we use to assess whether documentation is good. diff --git a/docs/contributing/documentation/writing_good_docs.md b/docs/contributing/documentation/writing_good_docs.md index ba58a3b..be35450 100644 --- a/docs/contributing/documentation/writing_good_docs.md +++ b/docs/contributing/documentation/writing_good_docs.md @@ -138,9 +138,9 @@ Documentation should be structured to minimize maintenance burden: ### Version Compatibility -Features that only apply to specific versions of Gardenlinux or supporting tools -should be marked as such using markdown admonishments or any other suitable -formatting to make them stand out. +Features that only apply to specific versions of Garden Linux or supporting +tools should be marked as such using markdown admonishments or any other +suitable formatting to make them stand out. Breaking changes between versions should be indicated in an appropriately colored warning or info box at the top of the document. @@ -183,3 +183,11 @@ Use this checklist when reviewing or submitting documentation: - [ ] Breaking changes highlighted (if applicable) - [ ] Known issues section included (if applicable) - [ ] External dependencies documented (if applicable) + +## Next Steps + +Before you get started, you might want to check out the following docs: + +- [Documentation Workflow](./documentation_workflow.md) +- [How to Documentation - Adding Repos to This Hub](/how-to/documentation/adding-repos.md) +- [How to Documentation - Working With the Aggregator Locally](/how-to/documentation/working-locally.md) From c4c0440aade76c457f86810835d381bde2f6ee8e Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Thu, 9 Apr 2026 13:40:19 +0200 Subject: [PATCH 5/5] Docs: Change Checklist to checkmarks Signed-off-by: Tiara Lena Hock --- .../documentation/writing_good_docs.md | 46 +++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/contributing/documentation/writing_good_docs.md b/docs/contributing/documentation/writing_good_docs.md index be35450..bf493c2 100644 --- a/docs/contributing/documentation/writing_good_docs.md +++ b/docs/contributing/documentation/writing_good_docs.md @@ -157,32 +157,32 @@ Use this checklist when reviewing or submitting documentation: ### Core Markers -- [ ] All code and commands are tested and working -- [ ] Prerequisites are clearly stated -- [ ] Expected output is shown for verification steps -- [ ] Document has clear structure with descriptive headings -- [ ] One main idea per paragraph -- [ ] Sentences are concise and use active voice -- [ ] Neutral and professional language throughout -- [ ] Gender-neutral language used -- [ ] Consistent terminology (no synonym confusion) -- [ ] Project-specific abbreviations link to Glossary -- [ ] All images have descriptive alt text -- [ ] Links use descriptive text (not "click here") -- [ ] Proper heading hierarchy maintained -- [ ] Code examples have syntax highlighting -- [ ] Color is not the only indicator in visual media -- [ ] All links verified as working -- [ ] Document is discoverable via navigation/index -- [ ] Cross-referenced from related documentation -- [ ] Clear ownership indicated +- ✅ All code and commands are tested and working +- ✅ Prerequisites are clearly stated +- ✅ Expected output is shown for verification steps +- ✅ Document has clear structure with descriptive headings +- ✅ One main idea per paragraph +- ✅ Sentences are concise and use active voice +- ✅ Neutral and professional language throughout +- ✅ Gender-neutral language used +- ✅ Consistent terminology (no synonym confusion) +- ✅ Project-specific abbreviations link to Glossary +- ✅ All images have descriptive alt text +- ✅ Links use descriptive text (not "click here") +- ✅ Proper heading hierarchy maintained +- ✅ Code examples have syntax highlighting +- ✅ Color is not the only indicator in visual media +- ✅ All links verified as working +- ✅ Document is discoverable via navigation/index +- ✅ Cross-referenced from related documentation +- ✅ Clear ownership indicated ### Conditional Markers -- [ ] Version compatibility noted (if applicable) -- [ ] Breaking changes highlighted (if applicable) -- [ ] Known issues section included (if applicable) -- [ ] External dependencies documented (if applicable) +- ✅ Version compatibility noted (if applicable) +- ✅ Breaking changes highlighted (if applicable) +- ✅ Known issues section included (if applicable) +- ✅ External dependencies documented (if applicable) ## Next Steps