Documentation Style Guide¶

Status: Active

Overview¶

This document defines the official writing standards for all Nivron documentation.

Its purpose is to ensure every page follows a consistent structure, writing style and navigation model, allowing the documentation portal to evolve as a coherent technical product.

Objectives¶

Objective	Description
Consistency	Apply a uniform structure across all documentation.
Readability	Make technical content easy to navigate and understand.
Maintainability	Simplify long-term documentation maintenance.
Quality	Treat documentation as an integral part of the product.

Standard Page Structure¶

Unless a technical reason exists, every page should follow this structure:

Overview
Purpose
Architecture
Implementation
Examples
Related Topics
Next Step

Headings¶

One H1 title per page.
H2 for primary sections.
H3 only when additional hierarchy improves readability.

File Naming¶

Documentation files should:

Use lowercase.
Separate words with hyphens.
Reflect the documented concept.

Examples:

control-plane.md
database-architecture.md
identity-foundation.md

Links¶

Use relative links whenever referencing other documentation pages.

Example:

../reference/database-schema-reference.md

Avoid absolute links within the documentation repository.

Every page should include a Related Topics section linking to conceptually related documents.

Code Blocks¶

Always specify the language identifier.

Example:

print("Hello")

Tables¶

Prefer tables when comparing concepts, capabilities or implementation details.

Diagrams¶

Use Mermaid diagrams whenever they improve understanding of architecture, workflows or relationships.

Admonitions¶

Use Notes, Warnings and Tips only when they provide meaningful technical value.

Language Guidelines¶

Write in clear technical English.
Avoid unnecessary marketing language.
Prefer precise terminology over informal expressions.
Keep descriptions concise while preserving technical accuracy.

Documentation Principle¶

Documentation is part of the product.

A feature is not considered complete until its implementation and documentation are both delivered and reviewed.

Previous

← Documentation Flow Review

Next

Markdown Reference →