Documentation Guide

Documentation Style Guide for holm

Conventions for holm project documentation. When in doubt, follow existing patterns in docs/.

Structure

• All documentation lives in docs/
• Example applications live in examples/ with corresponding README files
• README.md content is synced with docs/index.md

Writing Style

Tone

• Relaxed, friendly, direct and concise — no unnecessary preamble
• Conversational but professional; use "we" and "you"
• Practical: emphasize what users can do and how
• Assume intelligence; don't over-explain basics
• No marketing bullshit or slop

Formatting

Headers

• Sentence case (e.g., "Quick start guide" not "Quick Start Guide")
• H1 for titles only, H2 for sections, H3 for subsections, H4 sparingly

Inline Code

• Backticks for file names (page.py), variable/function/package names (metadata, holm.App(), htmy — not FastAPI or Starlette), and code snippets (def page():)
• No backticks for URL paths: /users/{id}

Lists

• Don't overuse lists
• Bullet points for unordered, numbered for sequential
• Keep items concise; nest for sub-points

Emphasis

• Bold for key terms being defined, important concepts, feature names (file-system based routing)
• Italics for emphasis and when introducing terms ("Layouts are defined...")

Document Types

1. Conceptual Documentation

Explain concepts, architecture, and design decisions.

Examples: application-components.md, file-system-based-routing.md

Structure:

1. Brief introduction
2. Core concepts with clear definitions
3. Rules or guidelines (bullet points)
4. Examples
5. Cross-references

Notes:

• Use "Rules for X:" format for constraints (if applicable)
• Include practical examples after explaining rules

2. Step-by-Step Guides

Walk users through building something specific.

Examples: guides/quick-start-guide.md, guides/forms.md, guides/actions-with-htmx.md

Structure:

1. Introduction stating what will be built
2. Topics covered
3. Link to the corresponding example application
4. Prerequisites
5. Step-by-step instructions with code examples (corresponding example must be in examples/)
6. Explanation of key concepts as they appear
7. How to run the application
8. What to expect when running it, if it makes sense

Notes:

• Use directory tree diagrams for file structure, if applicable
• Use hl_lines to highlight important code, or new/changed lines when a guide builds on another
• Explain the "why" after the "what"
• Include complete file contents, not just snippets
• End with next steps

3. Quick Reference ("In a Hurry")

Fast overview; focus on "what" not "how". Example: in-a-hurry.md

Structure:

1. One-paragraph overview
2. Core technology stack
3. Key concept (file-system based routing)
4. Component summaries with brief examples
5. No step-by-step instructions

Notes: Extremely concise; bold key concepts; minimal code.