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.

How do you approach documentation in your projects?

Great tips, i'd add to remember who your target audience is, if you're tool is designed for end users, prioritize how to use it over technical details (& the opposite).

It's not easy, particularly if you developed it and have spent months immersed in all the detail. To emerge from that and imagine coming to it as a new user is pretty hard. I don't have much to add but I like your advice. I need to rewrite the docs for one of my projects and I'll be bearing your points in mind.

Maybe one other point I'd add is: have a clear idea of who you're writing for, and have different levels and styles of documentation for different types of users. Don't try to satisfy everyone in the same document. Divide the documentation up by intended readership.

i had ai create documentation on the project i'm working it and it made me feel dirty. lol

How did that go? Did it actually produce something usable?

it did and it was really good; that's why i felt so dirty. lol