skills.rest
joeledwardson
joeledwardsonCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

documentation

Write and maintain mkdocs-material project documentation with diagrams, callouts, and structured page templates.

1|1|Updated Nov 25, 2024
Search Tags:#documentation#markdown#mermaid#technical writing#adr#diagrams#mkdocs
One-click install
npx skills add https://github.com/joeledwardson/dev-setup --skill documentation-joeledwardson
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation
Source: https://github.com/joeledwardson/dev-setup/tree/main/configs/claude/skills/documentation
Command: npx skills add https://github.com/joeledwardson/dev-setup --skill documentation-joeledwardson

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? AI-generated documentation tends to be technically correct but reader-hostile: unexplained acronyms, prose where diagrams belong, and no visual hierarchy. This Skill enforces a concrete ruleset for writing docs that a reader with no prior context can actually use. ## Core Features & Use Cases - Writing rules: Expand acronyms on first use, name things before writing, diagram-first for anything with structure, and a standard mermaid colour palette reused across all diagrams. - Page templates: Ready-made structures for architecture overviews, module reference pages, Getting Started guides, and test documentation using the function-seam-control triad. - Project records: Conventions for dev logs (monthly files), ADRs, and code review archives, plus checklists for keeping docs in sync with code changes. - Use Case: When adding a new CLI entry point to a project, the Skill triggers updates to the Getting Started flowchart, index tables, and architecture map in the same commit. ## Quick Start Ask the assistant to write or update a documentation page for a module in your project following the documentation rules.

Frequently Asked Questions about documentation

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

FAQPage Schema
How do I write documentation that readers without context can understand?▼

Apply the user test before every line: expand acronyms on first use, add one clause of context for named products or companies, and explain causal claims inline. Pages with three or more domain terms should include a collapsible key terms table.

How do I set up mkdocs-material with mermaid diagram support?▼

Install with uv tool install mkdocs --with mkdocs-material, then configure pymdownx.superfences with a custom mermaid fence in mkdocs.yml. Omit navigation.instant because it breaks mermaid rendering on page navigation.

When should I use a diagram instead of prose in documentation?▼

Any page describing structure, flow, or layout must contain a diagram. If you are writing words like sits behind, flows from, or sits between, you are describing a diagram you have not drawn yet.

Does this documentation approach work with MDX or Rspress projects?▼

The writing and quality rules still apply, but MDX projects with a rspress.config file should use the separate mdx-documentation skill for MDX-specific setup. This skill targets mkdocs-material and plain Markdown.

Why do mermaid diagrams go blank when navigating mkdocs pages?▼

The navigation.instant theme feature breaks mermaid rendering on page navigation. Remove it from mkdocs.yml and rely on standard navigation features like navigation.tabs and navigation.indexes instead.

How do I keep documentation in sync with code changes?▼

Use the trigger checklist: new CLI entry points update the Getting Started flowchart, new routes update index tables, new env vars update the API keys section, and non-trivial decisions get an ADR. Docs change in the same commit as code.

Related Skills

Explore More Content & Communication Skills→
fieldspherefieldsphere
37

update-readme

Generate repository READMEs with startup instructions and Mermaid architecture diagrams.

Official
Advanced
GuilhermeBrancalhaoGuilhermeBrancalhao

aieos-exportar

Generates mkdocs.yml from on-disk content and validates the MkDocs build.

Community
Intermediate
ojiudezueojiudezue
1

vibememo

Capture software project decisions in structured JSON and generate narrative summaries.

Community
Advanced
spencerbeggsspencerbeggs

rspress-components

Integrate RSPress built-in components into MDX documentation pages.

Community
Intermediate