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/documentation_workflow.md b/docs/contributing/documentation/documentation_workflow.md new file mode 100644 index 0000000..136b15b --- /dev/null +++ b/docs/contributing/documentation/documentation_workflow.md @@ -0,0 +1,135 @@ +--- +title: Documentation Workflow +description: How to Contribute Documentation to Gardenlinux +order: 1 +--- + +# Documenting Gardenlinux + +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? + +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 roles: The +contributors and a documentation lead. + +### Contributors + +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. 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 + documentation lead if applicable +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 [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 +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 place +- Ensuring that the documentation pipeline is running and the documentation + website is accessible + +### Documentation Ownership + +Documentation ownership depends on the scope: + +- **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 + +## How to Submit Documentation Changes + +To contribute documentation to Gardenlinux: + +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 + +## The Review Process + +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. + +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. + +The review validates: + +- **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)