documentation-standards

Enforce Markdown, Mermaid, and technical-writing conventions for documentation.

15|2|Updated Dec 13, 2025

Search Tags:#documentation #markdown #open source #mermaid #technical writing #adr #readme

Ready to run

npx skills add https://github.com/d-padmanabhan/agent-engineering-handbook --skill documentation-standards-d-padmanabhan

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: documentation-standards
Source: https://github.com/d-padmanabhan/agent-engineering-handbook/tree/main/skills/documentation-standards
Command: npx skills add https://github.com/d-padmanabhan/agent-engineering-handbook --skill documentation-standards-d-padmanabhan

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

documentation-standards helps prevent unclear, inconsistent, and outdated project docs by enforcing concrete formatting, structure, and writing rules.

Core Features & Use Cases

Markdown and Mermaid formatting: Apply consistent header structure, code block conventions, lists, links, and diagram best practices.
Technical writing quality: Produce concise, audience-first documentation with neutral/imperative voice and active voice.
Diataxis-aligned structure: Choose a single primary documentation mode per page (tutorial, how-to, reference, or explanation) and keep the content focused.
README structure guidance: Use a reliable README template for installation, quick start, documentation links, contributing, and licensing.
Open source documentation norms: Follow standard expectations for essential files and project setup documentation.

Quick Start

Ask the agent to rewrite a project README and inline documentation to match the Documentation Standards, including Mermaid diagram best practices and a Diataxis-aligned section structure.

Frequently Asked Questions about documentation-standards

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I structure a README for an open source project?▼

To structure a README, include dedicated sections for installation, quick start, documentation links, contributing guidelines, and licensing. This standard format ensures new users can quickly navigate and adopt your open source project.

What is the Diataxi framework for technical writing?▼

The Diataxi framework guides technical writing by assigning a single primary mode to each page: tutorial, how-to, reference, or explanation. Choosing one mode keeps content focused and ensures documentation serves its exact audience need.

How do I format Mermaid diagrams in Markdown?▼

Formatting Mermaid diagrams in Markdown requires applying consistent code block conventions and diagram best practices. Using standardized formatting ensures diagrams render correctly and remain maintainable within technical guides and reference pages.

What are the best practices for writing audience-first documentation?▼

Writing audience-first documentation requires using concise, neutral, and imperative active voice. Tailoring the tone and structure directly to the reader's needs prevents unnecessary complexity and maintains clear technical communication.

How do I apply consistent Markdown formatting conventions across a project?▼

Consistent Markdown formatting applies standardized header structures, code block conventions, lists, and links. Enforcing these formatting rules across technical guides and reference pages prevents outdated and unclear project documentation.