documentation_rules

Documentation Rules

Rules for creating and maintaining documentation files to minimize context window usage while maintaining clarity.

Core Principles

Minimize context usage: Every word, section, and file consumes context. Remove anything that doesn't directly serve the reader's immediate need.

Single source of truth: Each concept, rule, or process documented once. Reference, don't duplicate.

Concise language: Use the shortest clear phrasing. Prefer direct statements over explanations.

Content Rules

Avoid Redundancy

Within files:

• Don't repeat the same rule in multiple sections
• Don't restate the title in the first paragraph
• Don't summarize what you're about to say before saying it

Between files:

• Don't duplicate rules across multiple files
• Reference other files instead of copying content
• If overlap exists, consolidate into one file and reference it

Examples:

• Bad: "This document defines requirements. The requirements are defined below."
• Good: "Requirements:"

Remove Unnecessary Elements

Don't include:

• "Related Documentation" sections (use file structure and naming for discovery)
• Meta properties (Status, Last Updated, Related) in file headers
• Separator lines (---) unless grouping distinct sections
• Empty lines between every section (use sparingly)
• Introductory paragraphs that restate the title
• "Purpose" sections that repeat the filename
• Closing summaries that restate what was said

Do include:

• Direct statements of rules or requirements
• Essential context only
• Examples when they clarify ambiguity

Language Conciseness

Use:

• Direct commands: "Do X" not "Agents should do X" or "It is recommended that agents do X"
• Short phrases: "Required" not "This is a mandatory requirement"
• Active voice: "Create file" not "File should be created"
• Lists over paragraphs when possible
• Specific terms over general ones

Avoid:

• Hedging language: "should", "may", "consider" (use "must" or "do not")
• Filler phrases: "in order to", "for the purpose of", "it is important to note"
• Redundant qualifiers: "very important", "absolutely required"
• Explanatory preambles: "The reason for this is..." (state the rule, not why it exists unless critical)