Initially this will be a collection of random tips. My goal is to start recording the things I've learned from maintaining 990+ projects on GitHub and NPM.
Sections
- Optional TOC
- Brief description
- Basic example
- Installation instructions
- Usage information
- API docs
- CLI docs
- Unit tests
- Changelog (something I need to do more consistently)
- Contributing
- Author
- Licence and copyright
Style and formatting
- Headings
- Consistent formatting
- Code examples
- Syntax highlighting
- Only use a single H1 heading. There are few exceptions to this, like when a readme contains extensive API documentation.
- Avoid adding non-word characters or code to headings. There are a few reasons for this:
- Headings with code are less likely to be SEO-friendly. Given how important headings are for semantic context, this is alone should be enough of a deterrent (if you don't want visitors, why do docs at all?).
- Keeping headings simple makes it easy for documentation generators and markdown parsers to use headings for other things, like generating a table of contents, or cross-linking external documenation.
- It often makes the heading look busy and distracts from the actual content of the section. As cleaner and more visually appealing alternative is to add a fenced code block with the example below the heading.
- Add an extra newline after headings, before the content. This ensures that syntax highlighting will work consistently across all IDEs.