oss-write-docs

Write Docs

Contribute documentation that a maintainer would write — accurate, audience-aware, and verified against the actual code. Docs contributions have different mechanics than code PRs: you need to understand who reads the docs, verify every claim against source code, and test every example.

Purpose

Documentation contributions are undervalued by contributors and overvalued by maintainers. Most contributors skip docs because they don't feel like "real" contributions. But outdated docs cause more user frustration than most bugs, and maintainers rarely have time to keep docs current. This skill guides you through finding real documentation gaps, verifying accuracy against the code, and writing docs that match the repo's voice and style.

When to Use

• You've found outdated setup instructions (you followed them and they didn't work)
• Public API methods or functions lack documentation
• README assumes knowledge that new users don't have
• Code examples in docs don't run or produce wrong output
• Error messages reference docs that don't exist
• NOT for writing docs for your own project
• NOT for adding inline code comments — that's part of code contributions
• NOT when the repo has no docs infrastructure at all — discuss with maintainers first

Prerequisites

• Repo forked, cloned, and set up (from oss-prep-to-contribute)
• You've actually tried to USE the docs and found problems (not just skimming)
• Understanding of the area you're documenting (or willingness to build it)

Process

1. Identify documentation gaps

The best doc contributions come from actually using the docs and finding where they fail.

# Find docs files
find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -30
ls docs/ doc/ documentation/ wiki/ 2>/dev/null

# Check for docs framework
ls docusaurus.config.* mkdocs.yml conf.py book.toml .readthedocs.yml 2>/dev/null

# Find broken links in docs
grep -rn '\[.*\](.*\.md)' docs/ README.md | while read line; do
  file=$(echo "$line" | sed -n 's/.*(\([^)]*\.md\)).*/\1/p')
  [ -n "$file" ] && [ ! -f "$file" ] && echo "Broken link: $line"
done

# Find code examples and check if they reference current APIs
grep -rn '```' docs/ README.md --include="*.md" | head -20