Skip to content

Documentation Style Guide

This document defines the writing style, structure, and conventions used in ReFlux documentation.
Consistent style makes documentation easier to read, understand, and maintain.

General Writing Style

Always follow these rules:

  • Use clear, professional language
  • Avoid sarcasm and humor
  • Avoid marketing or promotional language
  • Prefer clarity over cleverness
  • Write complete sentences
  • Use active voice where possible

Documentation should sound calm, precise, and confident.

Tone

The preferred tone is:

  • Neutral
  • Informative
  • Practical
  • Direct

Avoid emotional or subjective language.

Headings

Use headings to create a clear hierarchy.

Guidelines:

  • One top-level heading per file
  • Use sections to group related topics
  • Avoid deep heading nesting
  • Headings should describe meaning, not format

Good headings explain what the reader will learn.

Paragraphs

  • Keep paragraphs short
  • One idea per paragraph
  • Use whitespace to improve readability

Long paragraphs should be split.

Lists

Use lists when:

  • Explaining steps or procedures
  • Enumerating responsibilities
  • Listing concepts or options
  • Summarizing key points

Use bullet lists by default.
Use numbered lists only when order is important.

Naming and Terminology

  • Use consistent terminology throughout all documents
  • Match names used in the codebase
  • Do not create multiple names for the same concept
  • Capitalize system and product names consistently

Define important terms once and reuse them consistently.

Describing Code Behavior

When referring to code:

  • Describe intent and behavior
  • Explain assumptions and side effects
  • Mention limitations or constraints
  • Avoid copying large blocks of source code

Documentation should explain why the code exists, not restate it.

Describing Business Logic

When documenting business rules:

  • Explain the real-world problem first
  • Describe how the system enforces the rule
  • Mention exceptions and edge cases
  • Clarify responsibility and ownership

Business logic documentation is often more valuable than technical descriptions.

Diagrams and Visuals

Use diagrams when:

  • Explaining architecture
  • Showing data or control flow
  • Describing interactions between modules
  • Explaining complex processes

Diagrams should support the text, not replace it.

Errors, Risks, and Edge Cases

Always document:

  • Known failure scenarios
  • Performance-sensitive areas
  • Data integrity risks
  • Security-relevant behavior

Explicitly documenting risks is encouraged and expected.

Avoid These Common Problems

Avoid:

  • Vague statements without explanation
  • Large unstructured text blocks
  • Repeating the same information across multiple pages
  • Restating obvious code behavior
  • Leaving unfinished placeholder text

Every document should provide clear value.

Documentation as a Living System

Documentation is never finished.

Expect to:

  • Revise and improve over time
  • Remove outdated information
  • Expand sections as systems evolve
  • Continuously improve clarity

Documentation should evolve alongside the codebase.