Documentation guide

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:

• Documentation Structure
• README Template

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

1. Check CONTRIBUTING.md for "Disabled Skills" section
   • If this skill is listed, it is disabled for this project
2. Check CONTRIBUTING.md for "Documentation Language" section
3. Check existing documentation structure
4. 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:

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

## Documentation Language

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

3. Start with README.md (essential)
4. Add LICENSE (for open source)
5. Add CONTRIBUTING.md (for team projects)
6. 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