Documentation

Iron Law

EVERY DOC IS SMALL, TAGGED, AND LINKED -- ONE CONCEPT PER FILE
YOU MUST keep every doc file under 800 tokens, include YAML frontmatter on every doc, and add a Related section at the bottom. No exceptions.

Violating the letter of this rule is violating the spirit of this rule.

Announce at start: "I am using the documentation skill to [write/update/review] [description]."

BEFORE PROCEEDING

Before writing any documentation:

1. Identify the domain and subdomain from the taxonomy in references/DOCUMENTATION_EXAMPLES.md
2. Confirm the file belongs in docs/<domain>/<subdomain>/ or docs/<domain>/<subdomain>/<subdomain2>/ (not a flat root file unless it's a cross-cutting standard)
3. Confirm no existing file already covers this concept: run grep -rF -- "<concept-title>" docs/ -- if a match exists, link to it instead of duplicating

[+] All 3 met -> proceed to write [-] Any unmet -> resolve before writing a single line

Step 1: Determine Documentation Type

Step 2: Apply Frontmatter and Linking Rules

Every docs/ file MUST begin with YAML frontmatter -- schema in references/DOCUMENTATION_EXAMPLES.md.

Required fields: title, description, domain, subdomain, tags, related.

• description MUST be one concrete sentence that answers: what exactly does this file cover?
• tags MUST include domain and subdomain as the first two entries
• related uses relative paths from the file's own directory

Every doc file MUST end with a ## Related section with at least one annotated link.

Document Mode vs Thread Mode

All files in docs/ MUST be Document Mode -- readable independently, with no assumed conversational context. Thread Mode writing (responses that only make sense inside a conversation) belongs in chat, not in documentation. If a paragraph requires "as discussed above" or "in the previous message," it is Thread Mode. Rewrite it or cut it.

Formatting Standards

1. Use markdown for all documentation
2. Include a Table of Contents for documents with 3+ sections
3. Use code blocks with language tags for all code examples
4. Use relative links -- verify they resolve from the file's directory
5. Keep file <=800 tokens; split at concept boundaries if longer
6. Use ASCII-only text (no Unicode characters) -- replace non-ASCII arrows, em/en-dashes, math operators, and box-drawing chars with ASCII equivalents (-> -- - <= >= != | - +)

Step 3: Review Checklist

Before presenting documentation, verify:

1. YAML frontmatter is present with all required fields
2. File is in the correct domain/subdomain directory
3. File is <=800 tokens
4. All relative links resolve correctly from the file's directory
5. Code examples have language tags
6. No content duplicated from another file -- linked instead
7. ## Related section is present at the bottom
8. Documentation matches current code state
9. All acronyms spelled out on first use -- no unexpanded project-specific or technical abbreviations (see Acronym Rule in the writing-skills skill)
10. Relevant docs/INDEX.md and docs/<domain>/INDEX.md updated to include this file

[+] All pass -> documentation is ready to present [-] Any unmet -> resolve all failing items before presenting

Rationalization Prevention

Red Flags -- STOP

• Doc file over 800 tokens -- STOP. Split at the second concept.
• Missing YAML frontmatter -- STOP. Add the full block before continuing.
• Missing ## Related section -- STOP. Add at least one annotated link.
• Two files covering the same concept -- STOP. Delete one; link from the other.
• Updating code without checking related docs -- STOP. Update stale docs first.

Related Skills

• writing-skills -- skill authoring standards, anatomy gate, and skill-reviewer dispatch pattern for validating completed skills

Reference

For the domain taxonomy, frontmatter schema, and guide template, see references/DOCUMENTATION_EXAMPLES.md.

Documentation principles: references/DOCUMENTATION_PRINCIPLES.md

Source: JPEGtheDev/story-to-ship — distributed by TomeVault.