Documentation Writing Guidelines

Clear documentation balances readability with AI processing efficiency through structured formatting, progressive disclosure from overview to details, and a 500-line rule that breaks lengthy content into scannable sections with references to dedicated resources.

Use progressive disclosure: lead with a high-level problem statement, follow with concrete code examples, organize with clear headings and lists, maintain consistent Markdown formatting, include frontmatter, and cap the main file at 500 lines by moving detailed content to separate reference files.

Apply scannable structure through hierarchical headings, bullet points, short paragraphs, code blocks with language hints, and consistent formatting conventions that help readers—human and AI—quickly find information without cognitive overload.

The 500-line rule improves both human readability and AI context efficiency by preventing information overload, reducing review cycles, and forcing content organization that separates essential guidance from detailed references.

Yes. This Skill applies to README.md files, SKILL.md context documentation, dev guides, getting-started resources, and other Markdown-based files, enforcing kebab-case naming, consistent formatting, code-block language hints, and progressive disclosure across all file types.

Show, don't just tell: concrete code examples and actionable patterns enhance understanding faster than abstract explanations alone, reducing ambiguity and providing immediate, applicable guidance for implementing features or workflows.