When I first started working on OSS projects, I really struggled with documentation. But after a lot of trial and error, I learned a lot about writing clear and helpful docs. Working on several OSS projects has also taught me just how essential good documentation is to the success of a project. So, I'd like to share with you some of the tips that have helped me improve (in the hope that they will save you the same headaches I've experienced lol):
- Guide first : Start with simple guides that focus on common use cases to help users get started quickly.
- Show, don’t tell: Use screenshots & screencasts early & often to visually demonstrate features.
- More code than text: Prioritize clear, working code examples over lengthy text explanations.
- Use plausible data: Craft realistic data in examples to help users better relate & apply them to their projects. I use faker.js for this.
- Examples as stories: Write examples in Storybook to ensure accuracy & consistency between code & visuals.
- The reference follows the guide: If an advanced user is looking for all possible options of a component, they can find them in the same place as the guide.
- Pages can be scanned quickly: Break content into short, digestible sections for quick navigation and easy reading.
Here's a doc example where I've tried to implement these best practices.
How do you approach documentation in your projects?
