Documentation Guide Skill

Documentation Guide

This skill provides guidance on project documentation structure, README content, and documentation best practices.

Quick Reference

Essential Project Files

| File | Required | Purpose | |------|:--------:|---------| | README.md | ✅ | Project overview, quick start | | CONTRIBUTING.md | Recommended | Contribution guidelines | | CHANGELOG.md | Recommended | Version history | | LICENSE | ✅ (OSS) | License information |

Documentation Completeness Checklist

[ ] README.md exists with essential sections
[ ] Installation instructions are clear
[ ] Usage examples are provided
[ ] Contributing guidelines documented
[ ] License specified

Detailed Guidelines

For complete standards, see:

README.md Required Sections

Minimum Viable README

# Project Name

Brief one-liner description.

## Installation

```bash
npm install your-package

Usage

const lib = require('your-package');
lib.doSomething();

License

MIT


### Recommended README Sections

1. **Project Name & Description**
2. **Badges** (CI status, coverage, npm version)
3. **Features** (bullet list)
4. **Installation**
5. **Quick Start / Usage**
6. **Documentation** (link to docs/)
7. **Contributing** (link to CONTRIBUTING.md)
8. **License**

## docs/ Directory Structure

docs/ ├── index.md # Documentation index ├── getting-started.md # Quick start guide ├── architecture.md # System architecture ├── api-reference.md # API documentation ├── deployment.md # Deployment guide └── troubleshooting.md # Common issues


## File Naming Conventions

### Root Directory (UPPERCASE)

README.md # ✅ GitHub auto-displays CONTRIBUTING.md # ✅ GitHub auto-links in PR CHANGELOG.md # ✅ Keep a Changelog convention LICENSE # ✅ GitHub auto-detects


### docs/ Directory (lowercase-kebab-case)

docs/getting-started.md # ✅ URL-friendly docs/api-reference.md # ✅ URL-friendly docs/GettingStarted.md # ❌ Case issues docs/API_Reference.md # ❌ Inconsistent


## Examples

### Good README.md

```markdown
# MyProject

A fast, lightweight JSON parser for Node.js.

[![CI](https://github.com/org/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/org/repo/actions)
[![npm version](https://badge.fury.io/js/myproject.svg)](https://www.npmjs.com/package/myproject)

## Features

- 10x faster than standard JSON.parse
- Streaming support
- Type-safe with TypeScript

## Installation

```bash
npm install myproject

Quick Start

const { parse } = require('myproject');

const data = parse('{"name": "test"}');
console.log(data.name); // "test"

Documentation

See docs/ for full documentation.

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

MIT - see LICENSE


### Good CHANGELOG.md

```markdown
# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- New feature X

## [1.2.0] - 2025-12-15

### Added
- OAuth2 authentication support
- New API endpoint `/users/profile`

### Changed
- Improved error messages

### Fixed
- Memory leak in session cache

## [1.1.0] - 2025-11-01

### Added
- Initial release

Configuration Detection

This skill supports project-specific documentation configuration.

Detection Order

Check CONTRIBUTING.md for "Disabled Skills" section
- If this skill is listed, it is disabled for this project
Check CONTRIBUTING.md for "Documentation Language" section
Check existing documentation structure
If not found, default to English

Documentation Audit

When reviewing a project, check for:

| Item | How to Check | |------|--------------| | README exists | File present at root | | README complete | Has installation, usage, license sections | | CONTRIBUTING exists | File present (for team projects) | | CHANGELOG exists | File present (for versioned projects) | | docs/ organized | Has index.md, logical structure | | Links working | Internal links resolve correctly |

First-Time Setup

If documentation is missing:

Ask the user: "This project doesn't have complete documentation. Which language should I use? (English / 中文)"
After user selection, suggest documenting in CONTRIBUTING.md:

## Documentation Language

This project uses **[chosen option]** for documentation.
<!-- Options: English | 中文 -->

Start with README.md (essential)
Add LICENSE (for open source)
Add CONTRIBUTING.md (for team projects)
Create docs/ structure (for complex projects)

Configuration Example

In project's CONTRIBUTING.md:

## Documentation Language

This project uses **English** for documentation.
<!-- Options: English | 中文 -->

License: CC BY 4.0 | Source: universal-dev-standards

Agent Skills: Documentation Guide

Skill Files