madappgang/claude-code/documentation-standards

Trust tier 2
  • community
  • ext:[{"type":"config","description":"Configuration overrides"}]
Source check pending

Checking that the SKILL.md file is still in the repository.

Use when writing README files, API documentation, user guides, or technical documentation following industry standards from Google, Microsoft, and GitLab style guides.

Install

npx vskill@latest install madappgang/claude-code/documentation-standards

Semi-extensibleMentions customization, but needs skill-specific knowledge. Read the extensible skills standard

SKILL.md

Documentation Standards

Overview

Comprehensive documentation standards based on research from Google, Microsoft, GitLab, Red Hat style guides, and 60+ additional sources. Provides templates, best practices, and anti-pattern detection for AI agents writing documentation.

15 Best Practices (Ranked by Consensus)

UNANIMOUS (100% Agreement)
1. Use Active Voice and Present Tense

Why: Reduces cognitive load 20-30%, shortens sentences 15-25%

Implementation:

markdown
BAD (passive): The request is processed by the server.
GOOD (active): The server processes the request.
 
BAD (future): The program will save your file.
GOOD (present): The program saves your file.

Validation: Check for "is/are/was/were + past participle" patterns

2. Start with 5-Minute Quick Start

Why: 70% of visitors are first-time users, time-to-first-success critical

Implementation:

markdown
## Quick Start

npm install my-tool npx my-tool init npx my-tool start

 
Visit http://localhost:3000
 
That's it!

Validation: Can a new user succeed in under 5 minutes with zero context?

3. Use Progressive Disclosure (Three-Tier Structure)

Why: Accommodates all skill levels, reduces overwhelm

Implementation:

Tier 1: Quick Start (2-5 min)
  -> Copy-paste code, immediate success, no explanations
 
Tier 2: Tutorial (15-30 min)
  -> Step-by-step with explanations, build one feature
 
Tier 3: Reference (lookup)
  -> Complete API docs, searchable, advanced patterns
4. Use Second Person ("You")

Why: Increases engagement, reduces word count 15-25%

Implementation:

markdown
BAD: The user should configure the settings.
GOOD: Configure the settings.
 
BAD: One can install the plugin by...
GOOD: Install the plugin by...
5. Keep Sentences Under 25 Words

Why: Comprehension drops 30% when sentences exceed 30 words

Implementation:

markdown
BAD (42 words): The configuration file, which should be located in the
root directory of your project and named .claude, contains all the settings
that are required for the plugin system to function correctly and load
the appropriate agents.
 
GOOD (18 words): Place the `.claude` configuration file in your project
root. It contains settings for the plugin system and agents.
6. Use Lists and Tables for Comparison

Why: 70% faster comprehension vs paragraphs

Implementation:

markdown
## Prerequisites
 
Before starting, you need:
-[ ] Node.js 18+ installed
-[ ] Git access to GitHub
-[ ] API token configured
 
## Tool Comparison
 
| Tool | Best For | Stars | Learning Curve |
|------|----------|-------|----------------|
| Docusaurus | React | 55k+ | Medium |
| VitePress | Vue | 12k+ | Low |
STRONG (67%+ Agreement)
7. Use Language-Specific Documentation Tools

Why: Deep language integration, automatic type inference

Decision Matrix:

Language -> Tool:
- TypeScript -> TSDoc comments + TypeDoc generator
- Python -> Google/NumPy docstrings + Sphinx
- Rust -> /// comments + rustdoc
- Go -> Plain comments + godoc
- Java -> Javadoc
8. Follow Diataxis Framework

Why: Clear taxonomy reduces confusion

Four Types:

TypePurposeLengthWhen to Use
TutorialTeach by doing15-60 min"I'm new, show me"
How-ToSolve problem5-15 min"I need to do X"
ReferenceDescribe what existsAs needed"What parameters?"
ExplanationClarify concepts5-30 min"Why does this work?"
9. Show Code Examples with Expected Output

Why: Users know what success looks like

Implementation:

markdown
### Example: Fetching User Data
 
**Code:**

const user = await api.getUserById('user-123'); console.log(user.name, user.email);

 
**Expected Output:**

John Doe john@example.com

 
**Error Case:**

const user = await api.getUserById('invalid-id'); // Throws: NotFoundError: User with ID 'invalid-id' not found

10. Provide Troubleshooting Section
Why: 50%+ of support questions are error-related
Template:
markdown
## Troubleshooting
 
### Issue: Command not found
 
**Symptom**: `/implement` returns "command not found"
**Cause**: Plugin not enabled
**Solution**:
1.Check `.claude/settings.json`
2.Run `/plugin reload`
3.Restart if needed
 
**Prevention**: Verify with `/plugin list`
11. Organize by Task ("How do I...")
Why: Users think in terms of goals, not architecture
Implementation:
markdown
## Guides
 
### How-To Guides (Task-Oriented)
-[How to deploy to production](deploy.md)
-[How to add authentication](auth.md)
-[How to handle file uploads](uploads.md)
12. Add Prerequisites Checklist
Why: Eliminates invisible barriers for beginners
Template:
markdown
## Prerequisites
 
Before starting, ensure you have:
 
-[ ] Node.js 18+ installed ([Download](https://nodejs.org))
-[ ] Basic JavaScript knowledge
-[ ] Text editor (VS Code recommended)
AI-SPECIFIC
13. Verify Examples Actually Work
Why: Prevents hallucination and outdated examples
Process:
  1. Read function implementation
  2. Extract actual parameters and return type
  3. Test example code
  4. Document actual output
14. Ground Documentation in Source Code
Why: Prevents documenting non-existent features
Process:
  1. Read source code FIRST
  2. Only document features that exist
  3. Use actual type signatures
  4. If uncertain, qualify with "typically", "generally"
15. Add Version Tracking
Why: Users need to know if docs apply to their version
Template:
markdown
---
**Version**: v2.0.0
**Last Updated**: 2026-01-09
**Compatible With**: Claude Code 1.5+, TypeScript 5.0+
---
 
> **DEPRECATED**: This approach works but superseded by [New Approach](link)
7 Ready-to-Use Templates
Template 1: README Quick Start
Purpose: Project landing page with 5-minute setup Max Length: 80 lines Use When: Creating project README
markdown
# [Project Name]
 
[One-line description of what this does]
 
## Quick Start
 
Step 1: Install
npm install my-tool
Step 2: Initialize
npx my-tool init
Step 3: Start
npx my-tool start
 
Visit http://localhost:3000
 
That's it!
 
## Features
 
- Feature 1 (one-line description)
- Feature 2 (one-line description)
- Feature 3 (one-line description)
 
[See detailed feature list](docs/features.md)
 
## Documentation
 
- [Installation Guide](docs/installation.md) - Complete setup instructions
- [Configuration](docs/configuration.md) - All configuration options
- [API Reference](docs/api.md) - Complete API documentation
- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
 
## Community
 
- [Contributing](CONTRIBUTING.md) - How to contribute
- [Code of Conduct](CODE_OF_CONDUCT.md) - Community guidelines
- [Discussions](https://github.com/user/repo/discussions) - Ask questions
 
## License
 
MIT - See [LICENSE](LICENSE) for details
Template 2: TSDoc Function Documentation
Purpose: Document TypeScript functions Format: TSDoc standard Use When: Documenting public APIs
typescript
/**
 * Retrieves a user by their unique identifier.
 *
 * @remarks
 * This function includes user permissions and preferences in the response.
 * Results are cached for 5 minutes to reduce database load.
 *
 * @param id - User unique identifier (UUID format)
 * @param options - Optional fetch configuration
 * @param options.includePermissions - Include user permissions (default: true)
 *
 * @returns Promise resolving to User object with permissions
 *
 * @throws {NotFoundError} If user with given ID doesn't exist
 * @throws {UnauthorizedError} If caller lacks 'read:users' permission
 *
 * @example
 * Basic usage:
 * ```typescript
 * const user = await getUserById('user-123');
 * console.log(user.name, user.email);
 * // Output: John Doe john@example.com
 * ```
 *
 * @example
 * Error handling:
 * ```typescript
 * try {
 *   const user = await getUserById('user-123');
 * } catch (error) {
 *   if (error instanceof NotFoundError) {
 *     console.error('User not found');
 *   }
 * }
 * ```
 *
 * @see {@link createUser} for creating new users
 * @since 2.0.0
 * @public
 */
Template 3: Error Documentation
Purpose: Document common errors and solutions Organization: By symptom Use When: Creating troubleshooting guides
markdown
# Troubleshooting Guide
 
## Installation Issues
 
### Error: EACCES permission denied
 
**Symptom**: npm install fails with permission error
 
**Full Error Message**:
npm ERR! code EACCES npm ERR! syscall access npm ERR! path /usr/local/lib
 
**Cause**: Trying to install globally without proper permissions
 
**Solution**:
 
**Option 1 (Recommended)**: Install locally
npm install --save-dev my-tool npx my-tool
 
**Option 2**: Fix npm permissions
mkdir ~/.npm-global npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH
 
**Prevention**: Use local installation (avoid -g flag)
 
---
 
### Error: Module not found
 
**Symptom**: Import fails with "Cannot find module 'X'"
 
**Causes**:
1. Package not installed
2. Wrong import path
3. TypeScript configuration issue
 
**Solution**:
 
**Step 1**: Verify package is installed
npm list my-package
 
**Step 2**: Check import path matches package name
// CORRECT import { func } from 'my-package';
// WRONG import { func } from 'my-package/lib/index';
 
**Prevention**: Always install dependencies before importing
Template 4: Tutorial Structure
Purpose: Teach by doing Length: 15-30 minutes Use When: Creating beginner tutorials
markdown
# Tutorial: Building Your First REST API
 
**What you'll learn**:
-How to create a basic REST API
-How to define routes and handlers
-How to connect to a database
-How to handle errors
 
**Prerequisites**:
-[ ] Node.js 18+ installed ([Download](https://nodejs.org))
-[ ] Basic JavaScript knowledge
-[ ] Text editor (VS Code recommended)
 
**Estimated time**: 30 minutes
 
---
 
## Step 1: Set Up Project
 
Create a new directory and initialize npm:
 
mkdir my-api cd my-api npm init -y
 
**What this does**: Creates package.json with default settings
 
---
 
## Step 2: Create Basic Server
 
Create `src/server.ts`:
 
import express from 'express';
const app = express(); const PORT = 3000;
app.get('/', (req, res) => {   res.json({ message: 'Hello, World!' }); });
app.listen(PORT, () => {   console.log(Server running on http://localhost:${PORT}); });
 
**What this does**:
- Imports Express framework
- Creates Express application
- Defines route for GET /
- Starts server on port 3000
 
---
 
## Step 3: Test Your API
 
Start development server:
 
npm run dev
 
**Expected output**:
Server running on http://localhost:3000
 
Test the endpoint:
 
curl http://localhost:3000
 
**Expected response**:
{"message":"Hello, World!"}
 
Success! You've created your first API endpoint.
 
---
 
## What You've Built
 
You now have a basic REST API with:
- Express server
- TypeScript configuration
- First endpoint
- Error handling
 
## Next Steps
 
1. **Add a database**: [Tutorial: Connect to PostgreSQL](postgres.md)
2. **Add authentication**: [Tutorial: Add JWT Authentication](auth.md)
3. **Deploy**: [Guide: Deploy to Vercel](deploy.md)
 
---
 
## Troubleshooting
 
**Issue**: Server won't start
 
**Solution**: Check if port 3000 is already in use:
lsof -i :3000 kill -9 <PID>
Template 5: Changelog
Purpose: Track version changes Format: Keep a Changelog standard Use When: Every release
markdown
# Changelog
 
All notable changes documented here.
This is the start of the file. Read the full SKILL.md on GitHub.
Security
  • Security scanPassed, 98 of 100Pattern checks on the skill's files.
  • Model reviewPassed
See the full security report
Quality evaluation
  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
See evaluation results
Source
Popularity
Repository stars
272
Repository forks
32
7-day trend score
28
Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 6 May 2026, 5 months ago.
Extension points
  • configConfiguration overrides
Learn the extensible skills standard
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/madappgang/claude-code/documentation-standards/badge)](https://verified-skill.com/skills/madappgang/claude-code/documentation-standards)
Something wrong with this skill or its page? Tell us.