Documentation style guide

This guide sets the style shared by all of the Navin documentation (Platform, Navin Manager, Navin agent, services, SDK, API, skills and plugins). Every page exists in French and in English, with the same file name, the same headings in the same order and the same examples. The documentation site is built by tools/docs/build.py and checked by tools/docs/check.py (100 % coverage).

Page types

Type	Purpose	Title
Concept	Explain what something is, why it exists and how it fits with the rest.	A noun: "Service high availability"
Task	Do one thing, step by step, end to end.	A verb: "Install the Navin Manager on RHEL 9"
Reference	List every option, field, command, error code or port, without exception.	A noun: "Configuration reference"
Tutorial	A complete path to learn, with a visible result.	"Get started with ..."
Troubleshooting	Symptom, cause, fix.	"Troubleshoot ..."
Release notes	What is new, changed, fixed and known in a release.	"What's new in release 1.0"

Task page template

Every step says what it does and why, gives the exact command, the expected result and what to do when it fails.

# Install the Navin Manager on RHEL 9

One paragraph: what you get, who does it (role), how long it takes.

## Before you begin

- System: RHEL, Rocky or Alma 9 (x86_64). Check: `cat /etc/os-release`.
- Rights: an account with `sudo`.
- Network: port 8443 open from the operators' workstations.

## Steps

1. **Add the package repository.** The internal repository serves the signed packages; without it, `dnf` cannot
   find the package.

   ```bash
   sudo dnf config-manager --add-repo <repository-url>
   ```

   `<repository-url>`: address of the mirror repository of your organization.

   Expected result: `dnf repolist` lists the `navin` repository.

   If it fails: check the proxy (`/etc/dnf/dnf.conf`) and the certificate of the repository.

2. **...**

## Verify

Command or screen that proves the operation succeeded, with the expected output.

## Next steps

Links to what comes next.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |

Reference page template

One table per group, one row per option, no option left out, no "etc.":

Name	Type	Default	Required	Description	Example

Values (names, types, defaults, bounds, codes) are read in the source code, never guessed. A reference page drawn from the code is generated by a tool (--check reports a stale page) rather than written by hand.

Writing rules

• One level 1 heading per page (the title), then ## and ### sections, without skipping a level.
• First sentence: what the page lets the reader do or understand. Add a one line description: front matter when the page appears in a list of cards.
• Short sentences, active voice, present tense. Address the reader ("you").
• Interface elements in bold with their exact label: Services > Install.
• Commands in a code block with its language (bash, yaml, json, python, ts, go, java, sql, text), ready to copy. Values to replace are written <in-angle-brackets> and explained right after.
• Admonitions: :::note, :::tip, :::info, :::warning, :::danger, closed by :::, with blank lines around. :::warning for a risk of outage, :::danger for a loss of data or of security.
• Links are relative to the target .md file of the same tree (../operations/upgrade.md#before-you-begin).
• Product names are never translated: Navin Platform, Navin Manager, Navin agent, Control Plane.
• Typography: no em dash or en dash (U+2014, U+2013); use - or rephrase.
• Forbidden: "TODO", "coming soon", "TBD", lorem ipsum, screenshots with real data, secrets, real internal addresses. Examples use angle-bracket placeholders (<control-plane-url>, <harbor-host>, <token>), never an invented address.
• Language pairs: the English page and the French page say the same thing; an update always changes both.

Numbering and order

The order of a section follows the reader's path: overview, installation, configuration, use, operations, security, reference, troubleshooting. A sidebar_position: <n> front matter sets the place of a page in the menu when the alphabetical order does not fit.