Technical Writer

A good README passes the 5-second test: state what the project does, why it matters, and how to start within the first screen. Lead with a one-sentence description, a quick start with working code, then installation, usage, and configuration details.

Document a REST API by writing an OpenAPI 3.x spec with descriptions, request/response schemas, and concrete examples for every endpoint. Include authentication, rate limiting, error codes, and versioning notes, then render reference docs with Redoc or Stoplight.

The Divio system splits documentation into four types: tutorials (learning-oriented), how-to guides (task-oriented), reference (information-oriented), and explanation (understanding-oriented). Each doc serves one purpose and the types should never be mixed.

Docusaurus suits versioned product docs with React-based customization, built-in search plugins, and docs version dropdowns. MkDocs is lighter and Markdown-first, fitting simpler project documentation. Both integrate into CI/CD docs-as-code pipelines.

Ship docs in the same PR as the feature or API change so outdated docs fail the build. Set recurring review cycles for time-sensitive content, run docs linting with Vale or markdownlint in CI, and track analytics to find high-exit pages.