Skip to content

SKILL.md

Latest commit

 

History

History
209 lines (154 loc) · 6.78 KB

SKILL.md

File metadata and controls

209 lines (154 loc) · 6.78 KB
Raw
name documentation-standards
description Documentation best practices including Markdown formatting, Mermaid diagrams, technical writing, ADRs, and open source standards. Use when writing documentation, README files, markdown content, creating static diagrams in Markdown, or when asking about documentation structure, technical writing, or open source project setup. For interactive React Flow canvases in a SPA, use the reactflow-architecture-diagrams skill instead.

Documentation Standards

Mandatory Markdown gates are owned by the Markdown rule (${HANDBOOK_ROOT}/rules/800-markdown.mdc). This skill owns document design, Mermaid guidance, templates, and writing workflows.

Core Principles

  1. Audience-First: Write for your reader, not yourself
  2. Keep Current: Outdated docs are worse than no docs
  3. Show, Don't Just Tell: Use examples and diagrams
  4. Consistent Format: Follow established patterns

Hard Requirements (Writing)

  • No AI slop - remove filler, keep docs concrete and task-oriented
  • No Unicode em dashes or en dashes - never author U+2014 or U+2013; use commas, colons, parentheses, semicolons, or ASCII hyphens instead
  • Clickable navigation - if readers may want to open a repo file, directory, section, ADR, rule, skill, script, workflow, or config, make it a Markdown link. Use backticks only when the path is a literal value, not a navigation target.
  • Official terminology - use each vendor's current official product and service names, capitalization, and branding. Verify uncertain names against current vendor documentation. For example, write Amazon VPC, not AWS VPC; write AWS Lambda, not Amazon Lambda. Do not apply one naming prefix mechanically across a provider's services.

Voice

Prefer neutral/imperative phrasing - avoid "you/your" in professional docs. Canonical guidance: rules/810-documentation.mdc.

Diataxis Quick Guide

Use one primary documentation mode per page:

  • Tutorial - learning by doing
  • How-to guide - task completion
  • Reference - factual lookup
  • Explanation - concepts and rationale

Canonical Diataxis guidance lives in rules/810-documentation.mdc. Keep this skill concise and link back to the rule instead of duplicating detailed standards.

README Structure

# Project Name

Brief description of what this project does.

## Features

- Feature 1
- Feature 2

## Installation

```bash
npm install my-project

Quick Start

import { thing } from 'my-project';
thing.doSomething();

Documentation

Link to full docs.

Contributing

Link to CONTRIBUTING.md.

License

MIT - See LICENSE.


## Markdown Best Practices

### Headers
- Use `#` hierarchy (don't skip levels)
- Keep headers concise
- Use title case for headings, preserving established acronyms and product names

### Code Blocks
````markdown
```python
def hello():
    print("Hello, World!")


### Lists
```markdown
- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Another item
```

### Links and References
```markdown
[Link text](https://acme.com)
[Reference link][1]
Python rule (`${HANDBOOK_ROOT}/rules/200-python.mdc`)
Bash rule (`${HANDBOOK_ROOT}/rules/140-bash.mdc`)

[1]: https://acme.com
```

Prefer clickable same-repo references:

- Good: `Python skill (`${HANDBOOK_ROOT}/skills/python-development/SKILL.md`)`
- Avoid for navigation: `` `skills/python-development/` ``
- Good for literals: `` `src/app.ts` `` when discussing a path value or config example

### Tables
```markdown
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
```

## Interactive vs static diagrams

- **Static (Markdown):** Mermaid in this skill and in `rules/800-markdown.mdc`.
- **Interactive (React SPA):** `@xyflow/react` patterns, playbook, and rule **`rules/815-reactflow-diagrams.mdc`** - use skill **`skills/reactflow-architecture-diagrams/`**. See static versus interactive diagrams (`${HANDBOOK_ROOT}/skills/reactflow-architecture-diagrams/references/static-vs-interactive.md`) for a short comparison table.

### AI diagram tooling

Prefer tools that preserve a code-owned source of truth. Mermaid text in the repo is easiest to review, diff, and maintain.

| Tool | Best fit | Round-trip / ownership guidance |
|---|---|---|
| **Mermaid Chart AI** | Best fit for engineering-maintained diagrams | Generates/refines standard Mermaid and can export PNG, SVG, or MMD. Keep the `.mmd` / Mermaid block in the repo as source of truth. |
| **Eraser** | Good for nicer engineering visuals | Can import Mermaid and export PNG/SVG/PDF. Mermaid round-tripping is weaker, so treat exported Mermaid as a starting point and review manually. |
| **Lucidchart AI** | Good for polished business-friendly diagrams | Supports Mermaid input, but generated diagrams are not ideal for code-based round-tripping. Use for stakeholder diagrams, not canonical repo-maintained architecture diagrams. |
| **Napkin AI** | Best for presentation / infographic visuals | Exports PNG/SVG/PPT/PDF, but not Mermaid. Use for slides or narrative visuals, not engineering diagrams that must remain code-owned. |

Rule of thumb: if future maintainers need to edit it in Git, use Mermaid (or React Flow for interactive SPA diagrams). If the artifact is for a deck or executive narrative, exported visuals are acceptable as generated artifacts.

## Mermaid Diagrams

### Flowchart
```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

### Sequence Diagram
```mermaid
sequenceDiagram
    participant User
    participant API
    participant DB
    
    User->>API: Request
    API->>DB: Query
    DB-->>API: Result
    API-->>User: Response
```

### Architecture Diagram
```mermaid
graph LR
    subgraph Frontend
        A[React App]
    end
    subgraph Backend
        B[API Gateway]
        C[Service]
    end
    subgraph Data
        D[(Database)]
    end
    
    A --> B
    B --> C
    C --> D
```

## Technical Writing Tips

1. **Use active voice**: "The function returns a value" not "A value is returned"
2. **Be concise**: Remove unnecessary words
3. **Define acronyms**: Spell out on first use
4. **Use present tense**: "The function adds" not "The function will add"
5. **Include examples**: Show, don't just tell

## Detailed References

- **React Flow (interactive canvases)**: See `skills/reactflow-architecture-diagrams/SKILL.md` and `rules/815-reactflow-diagrams.mdc`
- **Markdown & Mermaid**: See Markdown and Mermaid (`${HANDBOOK_ROOT}/skills/documentation-standards/references/markdown-mermaid.md`)
- **Technical Writing**: See technical writing (`${HANDBOOK_ROOT}/skills/documentation-standards/references/technical-writing.md`)
- **Open Source**: See open source (`${HANDBOOK_ROOT}/skills/documentation-standards/references/open-source.md`)