documentation-writing

A README should include overview, installation, usage, and configuration sections with clear examples. Structure it with a project description, prerequisites, step-by-step setup instructions, runnable code samples, and contribution guidelines to help users understand and adopt your project quickly.

Document APIs using language-specific tools like JSDoc, docstrings, or rustdoc with function signatures, parameter descriptions, return types, and runnable examples. Include endpoint descriptions, request/response formats, and error handling to make your API discoverable and easy to integrate.

Structure tutorials with incremental steps, clear explanations of why each step matters, and checkpoints between sections. Break complex tasks into manageable chunks with examples and expected outcomes so users can follow along and verify progress at each stage.

Code comments should explain the 'why' behind logic, not just the 'what'. Use docstrings to describe function purpose, parameters, return values, and usage examples. Keep comments concise and maintainable, avoiding redundancy with self-documenting code.

Organize changelogs with sections for new features, bug fixes, breaking changes, and deprecations. Use clear language targeted at users, include version numbers and dates, and highlight migration steps for breaking changes so users understand the impact of each release.

Yes, core principles—clear structure, examples, prerequisites, and configuration details—apply to READMEs, API docs, user guides, and architecture documents. Adapt templates to your project type while maintaining consistency in organization, terminology, and runnable code samples.