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](./documentation-structure.md)
• [README Template](./readme-template.md)

README.md Required Sections

Minimum Viable README

# Project Name

Brief one-liner description.

## Installation

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

# 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

npm install myproject

## Quick Start

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

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

## Documentation

See [docs/](docs/) for full documentation.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## License

MIT - see [LICENSE](LICENSE)

Good CHANGELOG.md

# 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
2. If this skill is listed, it is disabled for this project
3. Check CONTRIBUTING.md for "Documentation Language" section
4. Check existing documentation structure
5. 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 | 中文 -->

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