ferrix/docs/STYLE.md

# Documentation style

The documentation follows the conventions of network equipment vendors'
technical documentation: Juniper TechLibrary, Cisco configuration guides,
and Nokia SR OS guides. Operators read these every day; Ferrix's
documentation should read like them. This file is the checklist.

## Topic types

Every page is one of three kinds, and its title says which.

| Type | Answers | Title pattern | Examples |
|---|---|---|---|
| Concept | What is it, how does it behave | `<Feature> Overview`, `Understanding <Feature>` | BGP Import Policy Overview |
| Task | How do I configure or operate it | `Configuring <Feature>`, `Example: Configuring <Feature>`, `Verifying <Feature>` | Configuring Prefix Limits |
| Reference | What exactly does this element do | The element's name, or `<Thing> Reference` | `max_prefixes`, Metrics Reference |

A feature page in the user guide combines them in this order, with these
section titles where they apply:

1. `Understanding <Feature>` or `<Feature> Overview`: what it is and how it behaves.
2. `Configuring <Feature>`: the task, with an example.
3. `Verifying <Feature>`: how to see that it works.
4. `Limitations` (or `Restrictions`): what is not supported.

## Titles and headings

- Title Case for page titles and section headings: "Configuring Route
  Origin Validation", "Default Import Checks".
- Headings are noun phrases or gerund phrases naming a feature or a task.
  Never a sentence, a question, a metaphor, or a story ("A route's way in",
  "Who may connect", "What it costs").
- Do not number headings in the text; the site numbers them.

## Sentences

- Present tense, active voice, declarative: "Ferrix rejects routes whose
  AS path contains the local AS number."
- The subject is the product, a component, or a protocol element: "Ferrix",
  "the daemon", "the BGP session", "the import policy", "the router". Use
  "you" for the operator's actions: "You can configure…", "To limit the
  number of prefixes, configure `max_prefixes`."
- Never "we", "us" or "our". Write "the local AS", "the local router",
  "routes that Ferrix originates".
- One idea per sentence; 12 to 25 words is typical.
- Open a concept with a definition: "Route origin validation (ROV) is a
  mechanism that…".
- Spell out an acronym at its first use on a page: "Resource Public Key
  Infrastructure (RPKI)". Common ones (BGP, AS, IP, TCP) need not be.
- State defaults explicitly: "By default, …" in prose; "Default:" in
  reference entries.
- Ranges and units: "1 through 65535", "600 seconds", "4,294,967,295".
- Introduce lists and tables with a sentence ending in a colon: "Ferrix
  rejects the following routes:", "Table 1 lists the default checks."
- Give reasons only where they affect an operational decision, and plainly:
  "This prevents a neighbor from directing traffic to a third party."
- No figurative language, idioms, rhetorical questions, aphorisms, jokes,
  marketing adjectives ("blazing", "seamless"), or colloquial verbs
  ("cut off", "draw traffic", "hand over").

## Terminology

Use the standard BGP and vendor term, not a paraphrase.

| Use | Not |
|---|---|
| accept, reject | take, refuse, judge |
| advertise, withdraw | announce to, tell, pass on (as a verb for advertisement) |
| receive | hear, be told |
| neighbor, peer | the other side |
| best path, active route | the chosen route, the one best route |
| session is established, torn down | comes up, goes down, is cut |
| install (in the kernel/FIB) | put in |
| routing table (Loc-RIB), Adj-RIB-In | the table |
| local preference (`LOCAL_PREF`) | how much it is preferred |
| next hop is resolved / unresolvable | can / cannot be reached |
| hold-down | kept down |
| configuration statement, field | setting |
| originate | announce our own |

Ferrix-specific terms are defined once, where they are introduced, and
then used consistently:

- **Held route**: a received route that was rejected for a reason that can
  change without a new UPDATE (RPKI invalid, ASPA invalid, unresolvable next
  hop). Ferrix re-evaluates held routes when that condition changes.
- **Learned route**: a route received from a neighbor, as opposed to an
  originated route.
- **Control community**: a community that restricts which neighbors a
  route is advertised to.

## Notes and admonitions

Use them for information that is not part of the main flow, and use the
right kind:

| Marker | For |
|---|---|
| `> [!NOTE]` | Additional information the reader may need. |
| `> [!TIP]` | A recommended practice or a shortcut. |
| `> [!IMPORTANT]` | Information that affects correct operation. |
| `> [!WARNING]` | An action or setting that can disrupt service. |
| `> [!CAUTION]` | An action or setting with security consequences. |

## Procedures

- Number the steps. Each step is one action, in the imperative: "Configure
  the neighbor's address and AS number."
- Follow a step with the configuration or command it needs, then the result
  where it matters: "The daemon reports that the configuration is valid."
- End a task with how to verify it.

## Configuration and command elements

- Field names, values, commands, file names and metric names in code
  font: `max_prefixes`, `PROVIDER`, `bgp --check`, `/metricz`.
- In the configuration reference, describe a field with a verb in the third
  person: "Specifies…", "Enables…", "Limits…". Give its default and range.
- Show complete, valid configuration fragments. Whole example
  configurations live in `docs/examples/` and are validated by CI.

## Examples and placeholders

- Use documentation addresses and AS numbers: 192.0.2.0/24,
  198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32; AS 64496 through 64511
  and 65536 through 65551.
- Name sample routers and peers plainly: `transit-a`, `customer-65536`.