Documentation is King
Code tells the machine what to do. Documentation tells the human why it does it and how to use it. Good documentation is the difference between a dead project and a thriving one.
Essential Files
README.md
The landing page of your project. Must answer: What is this? How do I install it? How do I use it?
CONTRIBUTING.md
The guide for contributors. Setup instructions, coding standards, and PR process.
CHANGELOG.md
A history of changes. What's new in each version?
Readme Driven Development
Most developers write code first, then docs. Try doing it backwards.
The Process
- Write the
README.mdfirst. - Describe how the feature should work.
- Write the code to make the README true.
This forces you to design a good API before you get lost in the implementation details.
# My Awesome Feature
## Usage
```js
const user = await getUser(1);
console.log(user.name);
```
// Now I just need to make this code work...
Tools of the Trade
As your project grows, a single README won't be enough. Use these tools to build full documentation sites.
Docusaurus
By Meta
Built with React. Used by Redux, Create React App, and millions of others.
MkDocs
Python-based
Simple, fast, and uses standard Markdown. Great for non-JS projects.
VitePress
By Vue.js
Extremely fast static site generator. The modern choice for Vue projects.