Skip to main content

Documentation Conventions

This page documents the standards and patterns used throughout these docs.

Johnny Decimal Structure​

What Gets Numbered​

LevelNumbered?Example
AreaYes10-19-infrastructure/
CategoryYes21-api-walkthrough/
Page/TopicNoauthentication/index.md

Why This Matters​

  • Numbers at area/category level: Provides structure and predictability
  • No numbers at page level: Allows easy insertion without renaming
  • Order via _category_.yml: Centralized control, easy to modify

File Naming​

Folders​

  • Use kebab-case: api-walkthrough, error-handling
  • Be descriptive: react-hook-form not rhf
  • Avoid abbreviations unless well-known

Files​

  • Main content: index.md or index.mdx
  • Diagrams: topic-name.drawio and topic-name.drawio.svg
  • Images: descriptive-name.png

Markdown Guidelines​

Headings​

  • One H1 (#) per page (the title)
  • Use H2 (##) for main sections
  • Use H3 (###) for subsections
  • Don't skip levels

Code Blocks​

  • Always specify the language
  • Use meaningful examples
  • Keep blocks focused (< 50 lines)
# Good: Focused example
def authenticate(token)
  User.find_by(api_token: token)
end

Tables​

  • Use for structured data comparisons
  • Keep columns minimal
  • Align consistently
  • Use relative paths for internal links
  • Use descriptive link text
  • Avoid "click here" or bare URLs

Diagram Standards​

Format​

  • Source: .drawio files (editable)
  • Rendered: .drawio.svg (for embedding)

Style​

  • Use consistent colors
  • Include legends for complex diagrams
  • Keep text readable at normal zoom

Writing Style​

Tone​

  • Direct and practical
  • Assume technical competence
  • Avoid unnecessary jargon

Structure​

  • Start with the "why" or context
  • Follow with the "what" and "how"
  • End with examples or next steps

Audience​

  • Primary: Mid-level engineers
  • Write for someone who knows programming but may not know the specific domain