# Documentation Style Guide — DjangoPlay Labs

**Project:** DjangoPlay Labs Documentation  
**Document Type:** Governance  
**Last Updated:** 2026-03-28  
**Version:** 1.0  

---

## 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:

```yaml
---
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](./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:

| Example        | Use           |
| -------------- | ------------- |
| `<domain>`     | Domain        |
| `<db_name>`    | Database name |
| `<db_user>`    | Database user |
| `<secret_key>` | Secret key    |
| `<email>`      | Email         |
| `<path>`       | File path     |

---

## 10. File Naming Conventions

Use lowercase with hyphens:

| Correct                    | Incorrect             |
| -------------------------- | --------------------- |
| system-design.md           | SystemDesign.md       |
| deployment-architecture.md | deployArchitecture.md |
| user-guide.md              | userGuide.md          |

---

## 11. Versioning Documentation

Documentation version format:

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