Good documentation is what separates a tool anyone can use from a tool only its creator can use. Without it, even the best software is inaccessible. Documentation serves multiple audiences: new users, existing users, contributors, and your future self.
The README
The README is the front door of your project. At minimum it should contain:
- Project name and a one-line description
- A screenshot or demo GIF showing the tool in action
- Installation instructions — step by step, with code examples
- A quick-start usage example
- Full API reference or a link to docs
- Contributing guidelines
- License
Writing Clear Instructions
Use the imperative mood: "Run npm install", not "You should run npm install." Number
sequential steps. Include code blocks for any commands or code. Test your instructions
on a fresh machine. Explain the why, not just the what.
API Documentation
For libraries and tools with a programmatic API, document every public function with: its signature, a description, its parameters (name, type, description), its return value, and an example. Tools like JSDoc, Sphinx, and Docusaurus can auto-generate API docs from code comments.
Tutorials vs. Reference
Tutorials are goal-oriented — they guide users through completing a specific task. Reference docs are information-oriented — they describe the system accurately and completely. Both are necessary.
Code Comments
Comments should explain why, not what. Avoid comments that restate what the code obviously does. Use them to explain non-obvious decisions, edge cases, and workarounds.
Changelog
Maintain a CHANGELOG.md that records what changed in each version. Follow the Keep a Changelog
format. Categorize changes as: Added, Changed, Deprecated, Removed, Fixed, Security.
Links & Resources
- Write the Docs — Community and conference dedicated to documentation.
- Keep a Changelog — Conventions for maintaining a changelog.
- JSDoc — API documentation generator for JavaScript.
- Make a README — Guide and template for writing a great README.
Assignment
Document your software in a README on GitHub.