diff --git a/README.md b/README.md index 67cbc15..8876812 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ To find out more, visit our ## Licensing Copyright 2025 SAP SE or an SAP affiliate company and GardenLinux contributors. -Please see our [LICENSE](LICENSE.md) for copyright and license information. +See our [LICENSE](LICENSE.md) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://reuse.software). diff --git a/docs/contributing/documentation/aggregation-architecture.md b/docs/contributing/documentation/aggregation-architecture.md index b9272a5..6577073 100644 --- a/docs/contributing/documentation/aggregation-architecture.md +++ b/docs/contributing/documentation/aggregation-architecture.md @@ -1,6 +1,6 @@ --- title: "Documentation Aggregation Architecture" -description: "Deep dive into how the documentation aggregation system works" +description: "How the documentation aggregation system works" order: 3 related_topics: - /contributing/documentation/documentation_workflow.md @@ -17,8 +17,8 @@ related_topics: # Documentation Aggregation Architecture -Deep dive into the design and implementation of the documentation aggregation -system. +This page describes the design and implementation of the documentation +aggregation system. ## System Overview diff --git a/docs/contributing/documentation/documentation_workflow.md b/docs/contributing/documentation/documentation_workflow.md index abf56da..7baaedd 100644 --- a/docs/contributing/documentation/documentation_workflow.md +++ b/docs/contributing/documentation/documentation_workflow.md @@ -21,7 +21,7 @@ This guide will provide you with a detailed overview over everything you need to 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 +documentation is good, check our guide about [Document Quality Markers](./writing_good_docs.md) ## When Is Documentation Necessary? @@ -82,8 +82,7 @@ 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**_. +However this may be implemented, _**documentation is a team effort**_. The responsibilities of this person are: diff --git a/docs/contributing/documentation/writing_good_docs.md b/docs/contributing/documentation/writing_good_docs.md index d131090..1ba255b 100644 --- a/docs/contributing/documentation/writing_good_docs.md +++ b/docs/contributing/documentation/writing_good_docs.md @@ -28,10 +28,10 @@ therefore optional. ### 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 documentation must be correct in an informational sense. 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: @@ -53,7 +53,7 @@ Each document should clearly state: 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 +headlines that are both a navigation aid and a thread through the topic. Another aspect of good readability is a well thought out **separation of @@ -95,11 +95,44 @@ operation outcomes in any instructional guides. Use examples liberally across the documentation for any document that advises readers to action. +#### AI-generated phrasing to avoid + +AI-assisted writing introduces recognizable patterns that reduce documentation quality. Avoid these categories when authoring (see also [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), [softaworks/agent-toolkit humanizer skill](https://github.com/softaworks/agent-toolkit/blob/3027f20f3181758385a1bb8c022d4041dfb4de84/skills/humanizer/SKILL.md), and [blader/humanizer](https://github.com/blader/humanizer/blob/1b48564898e999219882660237fde01bf4843a0f/SKILL.md)): + +- **`HYPE-OPEN` — Hype openers and filler adjectives** (`delve`, `dive into`, `embark`, `unlock`, `elevate`, `seamlessly`, `robust`, `comprehensive`, `cutting-edge`, `powerful`, `leverage`, `harness`, `empower`, `streamline`, `effortless`, `tapestry`, `intricate`, `interplay`, `realm`, `pivotal`, `crucial`, `nuanced`, `dynamic`, `multifaceted`, `paradigm`, `synergy`, `holistic`, `unleash`, `foster`). Example: "This guide will help you unlock the full potential of..." → "This guide covers..." +- **`TRANS-BLOAT` — Transitional bloat** (`Moreover`, `Furthermore`, `In conclusion`, `In summary`, `It's worth noting`, `It's important to note`). Example: "Furthermore, the builder supports..." → "The builder supports..." +- **`PROMO` — Promotional flourish** (`world-class`, `best-in-class`, `next-generation`, `revolutionary`, `game-changing`, `state-of-the-art`, `seamless`, `unparalleled`, `unrivaled`, `premier`). Example: "a next-generation build system" → "a purpose-built build system" +- **`HEDGE` — Contextual hedging openers** (`In today's fast-paced world`, `In the ever-evolving landscape of`, `As we all know`, `It goes without saying`). Delete the opener and start with the actual statement. +- **`PRONOUN-OVERREACH` — Presumptuous collective pronouns** (`we've all been there`, `let's explore together`, `join me on this journey`). Use second person or neutral framing instead. +- **`RHETQ` — Rhetorical-question openers** (`Ever wondered…?`, `What if I told you…?`). State the topic directly. +- **`CANONICAL-LINT` — Canonical style anti-patterns** (`please`, `kindly`, `note that` as filler, ornamental parentheticals such as `(and this is important)`). Remove the filler; keep the statement. +- **`EM-DASH-DRAMA` — Em-dash as rhetorical pause** — em-dash used before a hype word or as a dramatic mid-sentence aside (e.g., `— unlocking`, `— making it`). Legitimate parenthetical em-dashes are fine. +- **`LEGACY-PUFF` — Significance or legacy claims** (`has left a lasting legacy`, `has had a profound impact on`, `stands as a testament to`, `remains a cornerstone of`). Replace with a specific, verifiable statement or delete. +- **`NOTABILITY-PUFF` — Notability flex** (`widely regarded as`, `has gained recognition`, `experts agree`, `industry leaders have noted`) *(advisory)*. Cite a source or delete. +- **`ING-BLOAT` — Gerund-chain abstractions** — chains of -ing nouns as subject or object where a finite verb would be clearer. Example: "Configuring and deploying involves setting up..." → "To deploy, set up..." +- **`WEASEL` — Vague attributions** (`some say`, `many believe`, `it has been suggested`, `critics argue`). Name the source or rewrite as a factual claim. +- **`FUTURE-OUTLOOK` — "Challenges and Future Prospects" boilerplate** — section headings or closing paragraphs following the AI outline pattern (`Looking Ahead`, `Future Directions`, `The Road Ahead`). Replace with a specific heading or delete. +- **`COPULA-DODGE` — Copula avoidance** (`serves as`, `functions as`, `acts as`, `operates as`, `plays the role of` where "is" or a concrete verb suffices). Example: "serves as the single source of truth" → "is the single source of truth" +- **`NEG-PARALLEL` — Negative parallelisms** (`not just … but`, `not only … but also`, `more than just`). State what the subject does directly. +- **`RULE-OF-THREE` — Rule-of-three overuse** — exactly three adjectives or nouns grouped for rhetorical balance rather than precision *(advisory)*. Use the most precise term. +- **`SYN-CYCLE` — Synonym cycling** — using different words for the same concept within a short span (e.g., "build manifest", "build descriptor", "build specification" for the same thing). Pick one term and use it throughout. +- **`FALSE-RANGE` — False ranges** (`from … to …` implying broad coverage from two arbitrary endpoints). List specific items instead. +- **`BOLD-OVERUSE` — Boldface overuse** — bold applied to adjectives, adverbs, or transitional words for decoration rather than to mark key terms or critical warnings. +- **`TITLE-CASE` — Title case in headings** — capitalising non-proper words in headings. Use sentence case; preserve proper nouns and acronyms. +- **`EMOJI` — Emojis** — any emoji outside a code fence. Delete; replace with a VitePress callout if semantic meaning is needed. +- **`CHATBOT-ARTIFACT` — Chatbot artifacts** (`Certainly!`, `Great question!`, `As I mentioned`, `I hope this helps`, `Feel free to ask`). Delete entirely. +- **`SYCOPHANT` — Sycophantic tone** (`great job`, `well done`, `excellent choice`, `congratulations on`). Delete; state the outcome directly. +- **`OVER-HEDGE` — Excessive hedging** — two or more hedges in one clause (`might possibly`, `could potentially`, `may perhaps`). Use at most one hedge where genuine uncertainty exists. +- **`GENERIC-CONCLUSION` — Generic positive conclusions** (`By following these steps`, `Armed with this knowledge`, `You are now ready to`, `You now have a solid understanding of`). Delete or replace with a concrete next step or link. + +Filler words (`simply`, `just`, `easy`/`easily`, `actually`, `basically`, `obviously`) are a separate category governed by the style guide's banned-filler-word rule. + +These categories describe concrete patterns to avoid at authoring time. The "no vague polish" refusal policy still applies for reviewers: contributors must identify a specific pattern from this list, not request general rewriting. + ### 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 +Every person browsing documentation has different means and needs. They look for +different information and access documentation through different means. 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: @@ -201,6 +234,7 @@ Use this checklist when reviewing or submitting documentation: - ✅ Document is discoverable via navigation/index - ✅ Cross-referenced from related documentation - ✅ Clear ownership indicated +- ✅ No AI-tell phrasing (see AI-generated phrasing to avoid: HYPE-OPEN, TRANS-BLOAT, PROMO, HEDGE, PRONOUN-OVERREACH, RHETQ, CANONICAL-LINT, EM-DASH-DRAMA, LEGACY-PUFF, ING-BLOAT, WEASEL, FUTURE-OUTLOOK, COPULA-DODGE, NEG-PARALLEL, SYN-CYCLE, FALSE-RANGE, BOLD-OVERUSE, TITLE-CASE, EMOJI, CHATBOT-ARTIFACT, SYCOPHANT, OVER-HEDGE, GENERIC-CONCLUSION) ### Conditional Markers diff --git a/docs/how-to/reporting-issues.md b/docs/how-to/reporting-issues.md index f71ca46..64daf63 100644 --- a/docs/how-to/reporting-issues.md +++ b/docs/how-to/reporting-issues.md @@ -7,8 +7,8 @@ order: 999 # Reporting Issues In case you encounter any issues in your work with Garden Linux, and the -information in this documentation cannot help you, please don't hesitate to -reach out and report your issue. +information in this documentation cannot help you, open an issue or +reach out to report it. To do so, first identify which component of the project gives you troubles and open a new bug in the appropriate repository: @@ -19,10 +19,10 @@ open a new bug in the appropriate repository: - [Python Library - python-gardenlinux-lib](https://github.com/gardenlinux/python-gardenlinux-lib/issues/new/choose) In each repository you will find multiple issue types each with their own form. -Please read these forms carefully and provide as much information as possible +Read these forms carefully and provide as much information as possible about your issue. -## Issue Type Not Listed? +## Issue type not listed? For most problems you may encounter, the `bug` issue type might be the best fit your report. @@ -36,16 +36,15 @@ your case to know a couple of things: - What type of issue did you encounter? - What area or feature of Garden Linux did the issue show up in? -- What happened right before the issue occurred (please also provide the exact +- What happened right before the issue occurred (also provide the exact commands you used) - What did you already try to mitigate the issue (if applicable) -If possible, please also attach screenshots or log files to your report. +If possible, attach screenshots or log files to your report. Remember: _The more information you provide, the quicker reviewers can reproduce and analyze the issue._ ## Documentation Issue? -Did you find something to improve in this documentation? Please don't hesitate -to [open a new issue](https://github.com/gardenlinux/docs-ng/issues/new/choose). +Did you find something to improve in this documentation? [Open a new issue](https://github.com/gardenlinux/docs-ng/issues/new/choose). diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 7d62b21..8c50e99 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -5,7 +5,7 @@ order: 1 # Glossary -This glossary provides definitions for Garden Linux-specific terminology. If you would like to contribute additional terms or improve existing definitions, please visit our [contributing guide](../contributing/index.md). +This glossary provides definitions for Garden Linux-specific terminology. To contribute additional terms or improve existing definitions, visit our [contributing guide](../contributing/index.md). **Jump to:** [A](#a) · [B](#b) · [C](#c) · [D](#d) · [E](#e) · [F](#f) · [G](#g) · [I](#i) · [K](#k) · [L](#l) · [M](#m) · [N](#n) · [O](#o) · [P](#p) · [R](#r) · [S](#s) · [T](#t) · [U](#u) · [V](#v) @@ -287,7 +287,7 @@ The system and service manager used by Garden Linux. Garden Linux is purely syst ### test-ng -The testing framework used by Garden Linux for comprehensive system testing. See [ADR-0006](./adr/0006-new-test-framework-in-place-self-contained-test-execution.md) (new test framework), [ADR-0007](./adr/0007-non-invasive-read-only-testing.md) (non-invasive testing), [ADR-0008](./adr/0008-unified-and-declarative-test-logic.md) (unified test logic), [ADR-0010](./adr/0010-incremental-migration-and-coexistence-of-tests.md) (incremental migration), [ADR-0016](./adr/0016-minimal-host-dependencies-for-test-ng.md) (minimal host dependencies), [ADR-0021](./adr/0021-use-of-tiger-tool-in-tests-ng.md) (tiger tool usage), [ADR-0022](./adr/0022-test-ng-system-state-diffing.md) (system state diffing), and [ADR-0026](./adr/0026-test-ng-when-to-parsers.md) (when-to parsers) for comprehensive details on the test-ng architecture and design decisions. +The testing framework used by Garden Linux for system testing. See [ADR-0006](./adr/0006-new-test-framework-in-place-self-contained-test-execution.md) (new test framework), [ADR-0007](./adr/0007-non-invasive-read-only-testing.md) (non-invasive testing), [ADR-0008](./adr/0008-unified-and-declarative-test-logic.md) (unified test logic), [ADR-0010](./adr/0010-incremental-migration-and-coexistence-of-tests.md) (incremental migration), [ADR-0016](./adr/0016-minimal-host-dependencies-for-test-ng.md) (minimal host dependencies), [ADR-0021](./adr/0021-use-of-tiger-tool-in-tests-ng.md) (tiger tool usage), [ADR-0022](./adr/0022-test-ng-system-state-diffing.md) (system state diffing), and [ADR-0026](./adr/0026-test-ng-when-to-parsers.md) (when-to parsers) for details on the test-ng architecture and design decisions. ### TPM2