Documentation Writing Guide

This guide defines the standards and best practices for technical writing within the Tower Defense project. High-quality documentation is a core pillar of our system architecture.

1. The Diátaxis Framework

We categorize all documentation into four distinct types based on the user's intent and cognitive state. Do not mix these types in a single document.

Type	Purpose	User Intent
Tutorials	Learning a new skill	"I want to learn by doing."
How-To Guides	Solving a specific problem	"I have a goal to achieve."
Explanation	Understanding concepts	"I want to understand why/how."
Reference	Information retrieval	"I need technical facts/specs."

Guidelines for Each Type:

• Tutorials: Linear, step-by-step, guaranteed success. Avoid deep theory; link to Explanations instead.
• How-To Guides: Goal-oriented. Assume basic knowledge. Focus on a specific task (e.g., "How to scale a game server").
• Explanation: Discussion-based. Provide context, architectural reasoning, and trade-offs.
• Reference: Technical, concise, and exhaustive. Includes API endpoints, CLI flags, and database schemas.

2. Linguistic Standards

To ensure clarity and accessibility for international teams, follow these rules:

• Active Voice: Always specify who is performing the action.
  • Bad: "The game server is started by the API."
  • Good: "The API starts the game server."
• Simplified Technical English (STE):
  • Use short sentences (max 15-20 words).
  • Use short paragraphs (max 4-6 lines).
  • Use strong verbs (e.g., "modify" instead of "perform a modification").
• Clarity over Complexity: Avoid jargon, slang, or overly complex vocabulary.

3. Visual Documentation

Visuals reduce cognitive load in complex systems.

• Mermaid Diagrams: Use Mermaid for flowcharts, sequence diagrams, and state machines directly in Markdown.
• C4 Model: Use the C4 hierarchy (Context, Container, Component, Code) for architectural diagrams.
• Screenshots: Ensure screenshots are up-to-date and annotated if necessary.

4. Metadata & Frontmatter

Every Markdown file must include a YAML frontmatter block:

---
title: Page Title
sidebar_label: Short Label
sidebar_position: 10 # Controls ordering
slug: /custom-url # Optional
---

5. Quality Assurance (QA)

Our CI/CD pipeline enforces documentation quality:

1. Markdown Linting: Checked via markdownlint.
2. Link Checker: Ensures no broken internal or external links.
3. Spellcheck: Validates technical terms and English grammar.
4. Peer Review: All documentation changes must be reviewed via Pull Requests using the documentation label.

tip

When in doubt, prioritize Precision, Simplicity, and Necessity. If information is not necessary for the user's current goal, move it to an Explanation or remove it.