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?