Documentation Style Guide — DjangoPlay Labs

#1. Overview

This document defines documentation writing standards for DjangoPlay Labs documentation.

All documentation should follow this style guide to maintain consistency across projects.

#2. Document Structure

Each document follows the template for its type (templates/). A typical doc:

Header (frontmatter)
Overview
Main Sections
Examples / Commands
Tables / Diagrams
Related

#3. Document Header

Every document starts with a frontmatter header, not in-body metadata lines:

---
title: <page title>
description: <one sentence>
type: guide
since: 1.0.0
---

The fields, the doc types and the tooling are defined in DOCS_STANDARD.md.

#4. Heading Rules

Use consistent heading hierarchy:

# Title

## Section

### Subsection

#### Sub-subsection

Do not skip heading levels.

#5. Writing Style

Documentation should be:

• Clear
• Concise
• Professional
• Technical but readable
• Neutral tone
• Avoid slang
• Avoid unnecessary opinions
• Use active voice
• Use consistent terminology

#6. Formatting Rules

#Lists

Use tables for structured information.

Use bullet lists for:

• Features
• Steps
• Items

Use numbered lists for:

• Procedures
• Workflows
• Ordered steps

#7. Tables

Use tables for:

• Configuration values
• Comparisons
• Commands
• Environments
• Modules
• Services

#8. Code Blocks

Use code blocks for:

• Commands
• Configuration
• API examples
• SQL queries
• Scripts

#9. Placeholders

Always use placeholders for sensitive values:

#10. File Naming Conventions

Use lowercase with hyphens:

#11. Versioning Documentation

Documentation version format:

1.0 → Initial version
1.1 → Minor updates
1.2 → Minor updates
2.0 → Major changes