When I first started working on open source 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 open source 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 (hoping that they will save you the same headaches I've experienced ):

1️⃣ Guide first
Start with simple guides that focus on common use cases to help users get started quickly.

2️⃣ Show, don’t tell
Use screenshots & screencasts early & often to visually demonstrate features.

3️⃣ More code than text
Prioritize clear, working code examples over lengthy text explanations.

4️⃣ Use plausible data
Craft realistic data in examples to help users better relate & apply them to their projects. I use faker.js for this.

5️⃣ Examples as stories
Write examples in Storybook to ensure accuracy & consistency between code & visuals.

6️⃣ 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.

7️⃣ Pages can be scanned quickly
Break content into short, digestible sections for quick navigation and easy reading.

8️⃣ Features have several names
Use multiple terms for the same feature to improve searchability.

9️⃣ Document features multiple times
Cover features in different contexts (guides, HowTos, references) to enhance discovery.

🔟 Overview sections
Provide high-level summaries of feature groups to help users grasp concepts before diving into details.

1️⃣1️⃣ Beginner mode
Offer a simplified view of the doc to avoid overwhelming new users.

1️⃣2️⃣ Eat your own dog food
Regularly use your own doc to spot usability issues & improve user experience.

Here's a doc example where I've tried to implement these best practices.

Feel free to share your tips for writing good documentation, so that we can collectively help other open source projects!--

While the above is a little more focused on front-end/web projects I think one thing to keep in mind generally is also to meet the user where they are, or rather where they expect.
E.g. if you create a tool/plugin for vim, users will be thankful for having a vimdoc for reference. If you create a command line tool, a man page will be helpful for quick lookups.

I know that many projects today (especially when first getting set up) focus on a presentable readme but in many cases there are tools to automatically adapt this markdown text to the generally preferred documentation style and location.

Don't have to focus on perfection first but just having a pipeline set up which can then be iterated on over time.

For a more advanced approach I think you can get a lot out of understanding the principles of the Diataxis framework - but this is also larger up-front effort.

https://documentation.divio.com/

https://jamesg.blog/book.pdf

Documentation about documentation, hehehe