rsyslog/rsyslog
1
0
Fork 0
mirror of https://github.com/rsyslog/rsyslog.git synced 2026-03-19 14:09:30 +01:00
Code Issues Packages Projects Releases Wiki Activity
rsyslog/doc/STRATEGY.md
Rainer Gerhards 701236f653
doc: update to doc (improvement) strategy 
most importantly reflects necessary interim work.
2025-08-12 09:59:11 +02:00

7.8 KiB
Raw Blame History

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/<module>-<param-slug>.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: <module>-<param-slug>.rst (flat namespace).
  • Slug rules: lowercase; no spaces/punct; keep display name CamelCase.

B. Required Labels (top of file, exactly)

.. _param-<module>-<param-slug>:
.. _<module>.parameter.module.<param-slug>:
  • Add an alias label only for high-confidence, common typos: .. _<module>.parameter.module.<typo-alias>: (optional).

C. Header & Summary

  • Heading (H1): Original CamelCase parameter name.
  • One-sentence summary: Encapsulated for reuse:
.. summary-start
<single concise sentence; <=160 chars>
.. summary-end
  • Backlink line (separate): This parameter applies to :doc:../../configuration/modules/<module>.

D. Lightweight Metadata (Field List, fixed order)

Fill unknowns with (tbd); keep keys present.

:Name: <CamelCase>
:Type: string (see :doc:`../../rainerscript/constant_strings`) | integer | boolean
:Default: <value or (none)>
:Required?: yes | no
:Introduced: (tbd)
:Aliases: <comma-separated> | (none)
:Constraints: <brief rule> | (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/<module>.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:
.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Parameter
     - Summary
   * - :doc:`../../reference/parameters/<module>-<param-slug>`
     - .. include:: ../../reference/parameters/<module>-<param-slug>.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/<module>-<param-slug>.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).