What is the hub-and-spoke documentation model?

It is a structural pattern where a central 'hub' file provides high-level essentials and links to detailed 'spoke' files, allowing for progressive disclosure of information without overwhelming the reader.

How does this skill improve LLM performance?

By prioritizing structured, machine-readable formats like OpenAPI 3.1.1 and JSON Schema, it provides LLMs with unambiguous data contracts that are easier to interpret than unstructured human text.

Why should I avoid manual section numbering in markdown?

Manual numbering causes duplication when using tools like Pandoc, which automatically adds numbers via the --number-sections flag. Using semantic headings ensures cleaner, more maintainable documents.

Can this be used for existing project documentation?

Yes, the skill includes a standards checklist specifically designed for reviewing and refactoring existing documentation to meet modern AI-ready and PDF-compatible standards.

Documentation Standards

Name: Documentation Standards
Author: terrylica

byterrylica

•

Learning & Documentation

Establishes standardized markdown architectures and formatting rules optimized for both AI consumption and professional PDF generation.

About

This skill provides a comprehensive framework for creating documentation that serves both humans and LLMs effectively by implementing a machine-readable-first approach. It organizes content using a hub-and-spoke progressive disclosure model, ensuring essentials are easily accessible while detailed specifications are logically nested. Specifically optimized for Pandoc compatibility, it enforces semantic heading rules and eliminates manual section numbering to ensure flawless PDF exports. By standardizing file organization and content structure, it ensures high maintainability and consistency across project READMEs, technical specifications, and internal knowledge bases.

Key Features

Semantic markdown heading standards to prevent formatting duplication and manual numbering errors.
Standardized file organization patterns for global, skill-specific, and project-level documentation.
Pandoc-compatible formatting rules to automate section numbering in professional PDF exports.
2 GitHub stars
Hub-and-spoke progressive disclosure model for organized, navigable documentation structures.
LLM-optimized architecture prioritizing machine-readable specifications like OpenAPI and JSON Schema.

Use Cases

Defining clear data schemas and workflow contracts within complex software architectures.
Standardizing project documentation for better AI context retrieval and developer onboarding.
Preparing markdown files for professional, auto-numbered PDF generation using Pandoc.

About

Key Features

Semantic markdown heading standards to prevent formatting duplication and manual numbering errors.
Standardized file organization patterns for global, skill-specific, and project-level documentation.
Pandoc-compatible formatting rules to automate section numbering in professional PDF exports.
2 GitHub stars
Hub-and-spoke progressive disclosure model for organized, navigable documentation structures.
LLM-optimized architecture prioritizing machine-readable specifications like OpenAPI and JSON Schema.

Use Cases

Defining clear data schemas and workflow contracts within complex software architectures.
Standardizing project documentation for better AI context retrieval and developer onboarding.
Preparing markdown files for professional, auto-numbered PDF generation using Pandoc.