# Documentation Style Guide

This guide defines the standards for writing and maintaining rsyslog documentation. It ensures a consistent, professional style across all .rst files and helps contributors produce high-quality documentation.

## General Principles

- Audience: Primarily system administrators and developers. Content should also remain accessible to intermediate users.

- Tone: Professional, clear, and concise. Avoid personal references or conversational language.

- Focus: Prioritize actionable guidance (e.g., how to configure, troubleshoot, or understand rsyslog).

- Language: Use plain English. Avoid jargon and colloquialisms.

- Consistency: Every page should follow the same structure, terminology, and heading style.

## File Structure and TOC

- Master TOC: The index.rst file is the single entry point. Avoid using filesystem order.

- Preferred Topic Order:

  1. Introduction / Quick Start

  2. Configuration Basics

  3. Modules & Advanced Topics

  4. Troubleshooting

  5. Reference & API

  6. Community & Support

  7. Legacy Resources

- Use explicit ordering in .. toctree:: (avoid :glob:).

## Headings

Use underline-only adornments (no overlines). Assign a character per level:

- = Level 1 (document title)

- - Level 2

- ~ Level 3

- ^ Level 4

- “ Level 5

- + Level 6

Keep titles concise (≤ 60 characters).

## Text Formatting

- Line Length: Wrap lines at 80 characters.

- Code Blocks: Use :: or explicit code blocks (e.g., .. code-block:: bash).

- Inline Code: Use double backticks, e.g., `rsyslog.conf`.

- Links: Use inline links: rsyslog mailing list .

- Bold vs. Italic: - Bold: For UI elements or emphasized terms. - Italic: For alternative terms or emphasis.

## Cross-Referencing

- Use :ref: for internal cross-links, e.g., `See :ref:`troubleshooting`.`.

- Use consistent anchors, e.g., `.. _troubleshooting:`.

## Sections

Introduction/Overview - Describe what the feature/module is and why it is needed. - Include minimal examples.

Configuration

- Use rainerscript syntax for modern examples.

- Comment key parameters.

Support & Community

- Recommend modern resources first: AI assistant, GitHub Discussions, mailing list.

- Move outdated resources to Legacy Resources.

## Legacy Content

- Archive outdated guides and tutorials in legacy/.

- Use:

      .. note::
         This content is archived and may be outdated.

## Licensing & Legal

- Keep licensing information in licensing.rst.

- Use: `For license details, see :doc:`licensing`.`

## Examples and Code

- Provide minimal, complete examples.

- Always specify language:

      sudo systemctl restart rsyslog

## Maintenance

- Review docs at every release for outdated content.

- Check for deprecated parameters and move them to Legacy.

- Run make linkcheck to verify links.

## Metadata and JSON-LD

- Add a `.. meta::` block near the top of each page to keep HTML meta tags and JSON-LD in sync. Populate at least `:description:` and `:keywords:`, and set `:author:` when the page has a specific owner.

      .. meta::
         :author: Ada Writer
         :description: One-line summary reused in JSON-LD and previews.
         :keywords: rsyslog, queues, reliability

- FAQ pages (`faq/*.rst`) automatically emit `FAQPage` JSON-LD. Write each question as the section title and keep the answer in the section body so the extractor can pair them correctly.

- Generative AI assistants should preserve existing `.. meta::` blocks, update only the specific fields required for a change, and avoid inventing authors when none are provided.

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project

© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.