# The Rsyslog Documentation Strategy **Version: 1.1 (2025-08-12)** **Related Document:** `IMPLEMENTATION_PLAN.md` **Status:** Active This document outlines the official strategy for the rsyslog project's documentation. It is a living document, subject to revision as our tools and processes evolve. Its purpose is to ensure our documentation is **authoritative**, **sustainable**, and **intelligent**, serving both human system administrators and AI agents as a primary source of truth. --- ## What changed since 1.0 (summary) - Added a **Transitional Reference Workflow** for per-parameter pages until the code-driven pipeline (Doxygen -> Breathe) is ready. - Defined a **Parameter Page Standard** (paths, labels, metadata, summary include slices). - Clarified **light CI gates** for the PoC phase and the path to stricter enforcement. - Documented **case policy** (display CamelCase; case-insensitive), **stable labels/paths**, and **type semantics** linking. --- ## Core Principles 1. **Docs-as-Code:** Documentation is version-controlled, lives in the repo, and is integrated into CI/CD. 2. **Single Source of Truth:** Minimize duplication; prefer one canonical location with references elsewhere. 3. **Automation First:** Prefer generated/validated artifacts; add checks for drift, links, and structure. 4. **Hybrid Model:** Code-driven reference + human-authored narrative. --- ## Pillar 1: The Automated Foundation (Code-Driven Reference) **Goal:** Reference docs reflect source code truth. - **Authoritative Source:** C source defines modules, parameters, directives. - **Generation Toolchain:** Doxygen -> XML -> Breathe -> Sphinx. - **Handling Undocumented Changes:** 1) CI analyzes source and compares to docs. 2) On mismatch, **do not fail** (while in transition). 3) Open a GitHub issue tagged `documentation` + `autogenerated`. ### 1.1 Transitional Reference Workflow (Active) Until the code-driven pipeline is complete, we maintain **manual per-parameter pages** with stable IDs and paths that future generators must **preserve**. - **Paths (flat, RAG-friendly):** `doc/source/reference/parameters/-.rst` Example: `imdocker-dockerapiunixsockaddr.rst` - **Slugs:** lowercase; trim; remove spaces/punct; filenames and labels use the slug. Displayed names remain historical **CamelCase**. - **Stability Requirement:** When auto-generation lands, emit into **the same paths and labels** (no breaking changes; add redirects only if absolutely necessary). --- ## Pillar 2: The Narrative Layer (Human-Authored Guides) - **Validated Example Library (target state):** - Place complete examples in `doc/examples/`. - Guides use `.. literalinclude::` to avoid drift. - **Transitional exception (PoC):** - Inline examples are allowed temporarily in parameter pages and modules. - Prefer moving high-value examples to `doc/examples/` as soon as feasible. - **Diagrams as Code:** Prefer Mermaid via `sphinx-mermaid`. - **Content Migration:** Curate and integrate high-value external content into `doc/source/tutorials/`. --- ## Pillar 3: Quality & Contribution Framework - **Docs CI (target state):** 1) `sphinx-build -nW` (warnings as errors). 2) Linkcheck passes. 3) Drift detector verifies rsyslog terms/IDs against authoritative lists. - **Docs CI (PoC, current):** - Run `sphinx-build -b html doc/source doc/_build/html` (non-blocking). - Optional `linkcheck` (non-blocking; collect report). - Defer drift detector & strict warnings until post-transition. - **AI-Powered Review:** Optional PR comment bot for clarity/style. - **User Feedback:** “Edit on GitHub” links via `html_context`. --- ## Pillar 4: Distribution & Format Integration - **Man Pages:** Generated from RST via Sphinx man builder; included in release tarballs. - **Versioning Policy:** > Online docs reflect `main` (latest). For stable versions, authoritative docs are bundled with release tarballs. If using distro packages, prefer the documentation shipped with that package. --- ## Pillar 5: Ecosystem Integration - **External Projects:** Use `git submodule` + `intersphinx` for cross-references. - **Deployments:** Top-level `08_deployment_guides/` with platform subfolders. --- ## Pillar 6: Content Amplification & Authority - **Technical SEO:** `sphinx-sitemap`, and Schema.org metadata in templates. - **Strategic Syndication:** Publish key tutorials with `rel="canonical"` back to docs. - **Answer Hubs:** Summarize and link back to official docs. --- ## Parameter Page Standard (Transitional & Future-Proof) This contract applies now (manual) and must remain valid when pages are auto-generated. ### A. Location & Naming - **Location:** `doc/source/reference/parameters/` - **Filename:** `-.rst` (flat namespace). - **Slug rules:** lowercase; no spaces/punct; keep display name CamelCase. ### B. Required Labels (top of file, exactly) ```rst .. _param--: .. _.parameter.module.: ``` - Add an **alias label** only for high-confidence, common typos: `.. _.parameter.module.:` (optional). ### C. Header & Summary - **Heading (H1):** Original CamelCase parameter name. - **One-sentence summary:** Encapsulated for reuse: ```rst .. summary-start .. summary-end ``` - **Backlink line (separate):** This parameter applies to :doc:`../../configuration/modules/`. ### D. Lightweight Metadata (Field List, fixed order) Fill unknowns with `(tbd)`; keep keys present. ``` :Name: :Type: string (see :doc:`../../rainerscript/constant_strings`) | integer | boolean :Default: :Required?: yes | no :Introduced: (tbd) :Aliases: | (none) :Constraints: | (tbd) ``` > **Case policy:** rsyslog parameters are case-insensitive; CamelCase is recommended for readability (documented once per module page as a note). ### E. Sections (order) 1. **Description** — migrated/cleaned from the module page. 2. **Notes** — optional clarifications (e.g., “Do not prepend `?`”). 3. **Usage / Examples** — config snippets (`.. code-block:: rsyslog`). 4. **See also** — link back to the module page. ### F. Module Overview Page Adjustments In `doc/source/configuration/modules/.rst`: - Replace inline parameter docs with a **two-column list-table** (Parameter | Summary). **Do not** define any labels inside the table. - Pull the summary via **include slice** to avoid duplication: ```rst .. list-table:: :widths: 30 70 :header-rows: 1 * - Parameter - Summary * - :doc:`../../reference/parameters/-` - .. include:: ../../reference/parameters/-.rst :start-after: .. summary-start :end-before: .. summary-end ``` - Add a hidden toctree listing all parameter pages to avoid orphan warnings. --- ## Backward Compatibility Policy (Docs) - rsyslog maintains strong backward compatibility; parameters rarely change. - Document **Introduced** version when known; avoid “Deprecated/Removed” unless it actually happened. - The stable **paths and labels** above are part of this policy; generators must preserve them. --- ## Acceptance Checklist (PoC Phase) - [ ] Parameter pages exist at `reference/parameters/-.rst`. - [ ] Labels follow the **two required labels**; optional typo alias only if justified. - [ ] Module overview links to each parameter and includes summaries via include slices. - [ ] Field list present with fixed keys; `(tbd)` allowed. - [ ] Build succeeds with `sphinx-build -b html`. - [ ] Optional linkcheck report collected (non-blocking). --- ## Maintaining This Strategy - **Location:** `doc/STRATEGY.md` - **Discoverability:** Repo root `CONTRIBUTING.md` links here; PR template includes a checklist item. - **Enforcement:** During PoC, soft checks; post-transition, CI enforces strict gates (`-nW`, linkcheck, drift detector).