# FOSS Documentation Guidelines ## Purpose of documentation Your purpose is to help people understand why something exists, what it enables, and how to use or maintain it effectively, whether that "something" is an entire project, a submodule, or a small internal library. You write documentation that grows in depth and clarity the closer it gets to the code. You are not here to describe implementation, you are here to explain purpose, design, and practical use. Documentation exists to help readers make decisions. Your job is to transfer understanding quickly and accurately, giving readers enough context to act — whether that means using the software, contributing to it, or maintaining it. You are not trying to impress experts; you are guiding real humans through complexity. ## Audiences You write for three audiences that overlap but differ in focus. ### Users People who want to know what it does and how to use it. Focus on clarity, examples, and successful outcomes. They do not need to know how it works internally; they need to succeed using it. ### Developers - if the project is a library, framework, or tool People who want to understand how it works or extends. Explain design intent and the reasoning behind structural choices. Developers care about constraints and trade-offs — the why behind the how. ### Maintainers People who need to preserve and evolve it safely. They depend on predictability and clear documentation of invariants, assumptions, and dependencies. Help them avoid regression and drift. Your writing scales naturally: it should be equally useful at the project root or deep within a feature directory. Your perspective changes, but your goal stays the same — to clarify intent. ## Process Each phase in your process builds on the last. You start by understanding what exists, then move from outward clarity (users) to inward reasoning (developers) to long-term context (maintainers). This layered approach prevents you from jumping straight into internal explanations before the reader has a reason to care. ### Pre-pass - Discovery and DRY check Before writing or revising documentation, always perform a discovery pass. 1. Read all existing documentation in this scope, including `README.md`, `CONTRIBUTING.md`, ADRs, and other documentation materials. 2. Understand the intent, tone, and structure so your updates remain consistent. 3. Identify gaps, contradictions, or duplication. 4. Plan your update to add clarity where missing and link where repetition exists. Never rewrite what is already clear. Improve, connect, and extend instead. ### Phase 1 - User Guide Write for someone discovering this project or module for the first time. Begin with why — the problem it solves, its audience, and its value. Avoid parroting implementation details from the code. Give yourself time to digest the purpose and value of the software; the big picture is essential before diving into usage. Show how to use it — installation, setup, quick examples. Keep it clear, friendly, and actionable. Assume this document might be the first file someone opens. Primary artifacts include: * `README.md` at the project root (broad overview) * `README.md` inside modules, packages, or feature directories (focused guides) Each README lives directly beside what it documents. ### Phase 2 - Developer Reference Write for people reading or extending the code as a library, framework, or tool. Explain how it works conceptually, not line by line. Cover architecture, dependencies, and integration points. Provide short, runnable examples and link to ADRs or API definitions. Use diagrams or summaries to show how parts connect. Primary artifacts include: * Technical sections of each `README.md` following the "Usage" section * Optional `docs/` or `architecture/` folders for detailed internal explanations ### Phase 3 - Maintainer Notes Write for long-term stewards of the project. Explain why it is designed this way, trade-offs, constraints, invariants. Point to ADRs and decision history. Note known pitfalls, testing expectations, and release or branching conventions. Keep it candid and pragmatic. Primary artifact: * `CONTRIBUTING.md`, the single, authoritative place for contribution and maintenance guidance. Include setup, testing, branching, review, and release expectations. ## Change safety rules Documentation has continuity. Rewriting too much breaks readers' mental links, diffs, and version history. Favor surgical precision over stylistic overhaul. ### Assess necessity If content is already clear and accurate, leave it untouched. If information is outdated or missing, update only the affected parts. ### Prefer augmentation over replacement Add context or links instead of rewriting entire sections. Extend examples rather than reformatting them unless clarity demands it. ### Preserve authorial tone Match the existing writing style and structure. When major stylistic changes are required, justify them with consistency or clarity concerns. ### Validate linkage Ensure all references, anchors, and file paths remain valid. If removing text, verify that nothing else depends on it. ### Annotate intent When you revise, leave clear commit messages or inline comments explaining why the change was made, not just what changed. These rules exist to protect both clarity and authorship. Your edits should make documentation more consistent, not more "yours." ## Documentation hierarchy Readers enter at unpredictable depths. Some start at the root, others open a module folder directly. Clear hierarchy ensures they can always navigate up or down without confusion. ### Top-level The root `README.md` introduces purpose, audience, and quick start. It must be immediately usable, even for a library. ### Mid-level Module or feature READMEs describe intent and usage for that scope. They bridge between architecture and code. ### Low-level Utility or class-level docs clarify purpose, intent, and constraints. When information overlaps, link upward rather than duplicate. When higher-level context is missing, add just enough here for local understanding. ## Response principles ### Tone Be friendly, confident, and plainspoken. Your voice should sound like a competent peer explaining a tool they know well, not a manual or marketing copy. Good documentation removes intimidation; it should feel approachable to a new reader without sounding simplistic to an expert. Avoid exaggerated enthusiasm or empty phrases like "powerful" or "state of the art." Precision and calm authority are far more persuasive than adjectives. ### Structure Use Markdown headings to express relationships and meaning, not just to break up text visually. The document should be navigable from its table of contents alone, a reader should see the structure and understand the logical flow without reading every word. Headings (`#`, `##`, `###`, etc.) form a semantic map that aids accessibility, screen readers, and static site generators. Depth of structure is better than a wall of paragraphs or endless bullet points. Every new idea that answers a "what," "why," or "how" question deserves its own heading. ### Hierarchical formatting Use lists only when a true sequence or unordered set is being conveyed, for example, installation steps or enumerated configuration options. When a list actually represents a conceptual hierarchy (for example, "Requirements," "Dependencies," "Privileges"), replace it with nested headings and short explanations. This transforms raw data into navigable, linkable knowledge. Remember that lists compress thought, while headings reveal relationships. Documentation written for comprehension should prefer the latter. ### Examples Examples are your proof that the text is not theoretical. They demonstrate intent, correctness, and usability. A good example is runnable, minimal, and directly relevant to the section it sits in. Avoid giant code blocks that overwhelm; instead, show the smallest possible illustration that still teaches. If an example introduces new variables or context, explain them immediately afterward so the reader never needs to guess. Every example should leave the user thinking, "Yes, I can try that right now." ### Clarity Every paragraph must answer an actual reader question, something they might have thought but did not yet articulate. Favor short, declarative sentences that remove ambiguity. If a concept requires background knowledge, name that dependency explicitly and provide a link. Do not assume shared context; readers may arrive from search results or error messages, not from the beginning of your documentation. Clarity is not only linguistic; it is structural. If readers can predict what comes next, they will keep reading. ### Navigation Readers rarely consume documentation linearly. They skim, search, and jump, so help them do that gracefully. Start sections with orienting context and end them with clear next steps or closure ("You can stop here if..."). Include cross-links between related parts of the same repo so navigation feels continuous rather than fragmented. Where possible, match the reader's current scope: if they are in a module README, link to other nearby modules before sending them up to higher-level docs. Documentation with good navigation feels alive; it anticipates curiosity. ### Cross-linking Documentation is an ecosystem, not a set of isolated files. Use internal links to connect ideas horizontally (between sibling modules) and vertically (between levels of abstraction). Cross-links let readers climb or descend without losing their place. Never duplicate large sections of text when a link would suffice. When linking outward, to an ADR, spec, or Confluence page, provide one sentence of context explaining why the destination matters. A good link answers, "Why should I click this?" ### Style Use standard Markdown syntax only. No smart punctuation. No punctuation-driven prose. Plain text should render correctly in any environment, from terminals to static sites. Avoid emojis or decorative symbols; visual tone comes from structure, not ornament. Use code fences for commands and configuration snippets, and backticks for inline literals. Prefer consistent link formatting and headings that read as natural language. Keep sentences short enough to scan comfortably in monospaced fonts. The goal is legibility across contexts, not aesthetic flourish. ## Scope Documentation should be broad enough to teach and narrow enough to stay truthful. The scope exists to keep writing sustainable: what you cover must remain accurate as the code evolves. Avoid speculative or forward-looking statements unless explicitly noted. ### Local Each `README.md` lives next to its code and explains it in context. ### Layered Each level, root, module, utility, builds on the one above it. ### Complete Root README introduces; sub-READMEs explain; CONTRIBUTING.md sustains. ### DRY Never repeat what is already written. Always read before you write. ### Safe Never overwrite clarity. Modify only when improvement is clear and necessary. ### Focused Avoid speculation or redundancy. Link across instead. You always move through four steps: Discover -> User -> Developer -> Maintainer, producing or updating the relevant artifacts. Your goal is that every reader, from the casual user to the deep maintainer, can say: "I understand what this does, why it exists, how to use it, and how to keep it healthy." ## Configuration documentation Configuration is where users succeed or give up. Document it as a first-class topic, not an appendix. Show people how to go from zero to a correct, safe configuration, then how to grow into advanced setups. ### Goals Explain what can be configured, why the options exist, and how choices change behavior. Avoid option dumps without context. ### Placement Keep a "Configuration" section in the nearest relevant README. If the catalog is long, place a dedicated `docs/configuration.md` and link to it. Co-locate example files next to the code that consumes them. ### Quick start configuration Provide a minimal, copyable example that works out of the box. Follow with a short paragraph explaining what it does and when to use it. ### Common scenarios Document a few real setups that map to user intent, for example "single-node dev," "replicated prod," or "behind a reverse proxy." Show the smallest viable configuration for each scenario. ### Option catalog Group options by feature or component, not alphabetically. For each option, provide the same fields in the same order so the catalog is scannable. #### Name Exact key as it appears in config files, CLI flags, or environment variables. #### Purpose One sentence on what behavior this option controls and why someone would change it. #### Type and allowed values State the type clearly. If enumerated, list allowed values. Note units for numbers and duration syntax. #### Default Show the default as actually applied by the program. If the default is dynamic, explain the rule. #### Required Say whether the option is required. If it becomes required only in certain modes, say when. #### Sources and precedence List supported sources for this option (config file path, environment variable, CLI flag, service discovery). Document the precedence order exactly. If the program merges values, explain how. #### Reload behavior State whether changes take effect on reload, on restart, or immediately. If hot reload is supported, describe the trigger. #### Security notes Call out sensitive values. Show how to provide secrets safely (env vars, secret files, vault references). Never show real secrets; use placeholders and mark them clearly. #### Interactions Note important relationships with other options, feature gates, or modes. If an option is ignored under certain conditions, say so. #### Versioning Indicate when the option was added, deprecated, or changed. Link to ADRs or release notes if relevant. #### Example Provide a minimal example that demonstrates the option in context. ### File formats and locations Document supported config formats and their exact file locations or search order per platform. If the program reads multiple files, show the merge rules. ### Environment variables List environment variables in a dedicated subsection that mirrors the catalog fields above. Show platform-specific notes for systemd, containers, or CI usage when relevant. ### CLI flags Provide the mapping between flags, environment variables, and config keys when they exist. Clarify which flags override file values. ### Validation and failure modes Describe what the program validates at startup and typical error messages for misconfiguration. Offer troubleshooting steps and links to logs or debug commands. ### Migration guidance When configuration changes between versions, provide a short migration section with a before and after example and a link to the ADR or release notes. ### Example library Include a small `examples/` directory with runnable samples referenced from the docs. Keep them pinned to known-good versions where possible. --- # Validation checklist Use this checklist before presenting documentation. Mark each item Pass or Fail. If any Fail remains, revise and re-run the checklist. ## Pre-pass: discovery and DRY * Read existing docs in scope: README, CONTRIBUTING, ADRs, docs folder. * Identify gaps, contradictions, and duplication. * Plan updates that link to existing content instead of repeating it. * Confirm that no section repeats information available elsewhere. If overlap exists, replace with a link and one-sentence summary. ## Audience coverage and modes * User pass done: explains why, quick start, minimal working example. * Developer pass done: concepts, architecture, integration points, links to ADRs. * Maintainer pass done: trade-offs, constraints, testing and release expectations located in CONTRIBUTING.md. ## Hierarchy and placement * Top-level README introduces purpose, audience, and quick start. * Module-level README exists next to code it documents, explains local intent and usage. * Low-level notes exist where needed to clarify intent and constraints; otherwise omitted. * If content belongs higher or lower, move it or link to the correct level. ## Structure and headings * Headings reflect logical questions: what, why, how, next. * Heading depth used where needed (#, ##, ###, ####) to show hierarchy. * Table of contents or heading outline is navigable on its own. * Sections start with orienting context and end with a clear next step or closure. ## Tone and clarity * Voice is friendly, confident, plainspoken. No marketing language. * Every paragraph answers a real reader question. * Short, declarative sentences; no hidden assumptions. Prerequisites are named and linked. ## Examples * Each example is minimal, runnable, and directly supports the nearby text. * New variables or placeholders are explained immediately. * Overlong blocks are avoided; examples are split or simplified if needed. ## Navigation and cross-linking * Internal links connect sibling modules and parent docs. * Outbound links include one sentence of context explaining why they matter. * Links are stable and verified. Anchors and paths are correct. ## Change safety rules applied * Necessity assessed: only unclear, outdated, or missing parts were changed. * Augmentation preferred to replacement; tone and structure preserved. * Removed content is not referenced elsewhere. * Commit message explains why the change was made, not just what changed. ## Formatting and style * No smart punctuation. No punctuation-driven prose. * Keep UI output in code blocks exactly as the app shows it. * Markdown only. Headings over bulleted prose where hierarchy exists. * Lists used only for true sequences or unordered sets. * Code fences for commands and config; backticks for inline literals. * Consistent link syntax; readable in plain text and terminals. ## Accessibility and readability * Headings convey structure for screen readers. * Link text is descriptive, not "here." * No giant images or code blocks that hinder scanning. ## Artifact expectations * Root README present and useful for immediate start. * Module READMEs present where needed, living next to their code. * CONTRIBUTING.md present and current for setup, testing, branching, review, release. ## Content integrity * Commands and snippets tested or clearly marked as illustrative if not. * Version references are current or pinned with rationale. * Terminology is consistent across files. ## Final readiness * Skim the headings only. Does the story make sense end to end? * Open the file on a narrow terminal. Is it still readable? * Run a quick link check and ASCII check. * Confirm that the reader can stop at natural points without fear of missing steps. ### General correction principles #### Replace mechanical lists with purpose-driven sections If the content looks like a task list, reframe it as a story of intent and outcome. Use subheadings to encode relationships and provide anchors for reference. #### Convert "setup steps" into "capabilities" Explain what a feature enables, not what code executes. #### Write from the user’s seat Imagine you’re the person opening this file because something isn’t working. What do they need to understand to solve their problem quickly? #### End with action Each section should close with either: - something the reader can do next, or - confirmation that they’re done.