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.