Want to save time and frustration using open source tools? Want to grow your favorite open source project? It all starts with better documentation.
Use open source tools more easily with better documentation
You’ve stumbled across an awesome new open source tool that does exactly what you need. You just have one question… so you go to the documents. But wait – you can’t find the answer to your question anywhere in the documentation! Or maybe documentation doesn’t even exist. But you really wanted to use that tool… you haven’t found another tool that does exactly what you need in such a perfect way… so you either spend hours browsing Stack Overflow for an answer, or give up in frustration.
It doesn’t have to be that way.
With professional-quality documentation, written by experienced technical writers, you should be able to spin up quickly with new open source tools. As a technical writer, I’ll:
- Look for and fill gaps in documentation;
- Organize existing documents to make them easier to use;
- Improve documentation with images, code snippets, and visual design elements to present more comprehensive documents.
No more digging around forums and random web searches to use popular open source tools. Save time, relieve frustration, and get back to coding something cool.
Share your favorite open source projects with confidence
How often have you Tweeted about an open source project, but with a disclaimer that the documents stink? Or had to give someone a lengthy writeup about a well-known gap in an otherwise stellar tool? Or just didn’t bother to share an open source thing that you really love, because you had to spend two days fighting to get it configured properly, and don’t want to put another developer through that?
When open source projects are well-documented, you can share them with confidence. You don’t have to worry about whether someone will get stuck trying to use it, and then come back to you with a bunch of questions – or complaints about endless frustration.
More importantly, when an open source project is well-documented, it’s easy for new people to dive into the community, evangelize the tool, and contribute new features and code. If you want to grow an open source project, the fastest way to do it is by making it easy for people to use and contribute.
If you love an open source project, give it good docs.
What makes good open source documentation?
Open source documentation should be:
- Easy to find;
- Easy to understand;
- Easy to use.
Mostly, this comes down to identifying gaps in documentation, and organizing documentation effectively. This is where an experienced technical writer can transform a project’s documentation.
Most developers, while great at writing code, haven’t spent the time to develop the skills to document that code. We’ve all seen the open source project with a long list of methods – and that’s it. But as a new user to that open source project, you might be looking for a Getting Started guide, or maybe just an overview of the types of tasks you can do with the tool.
It’s a technical writer’s job to put themselves in the mindset of a user, whether new or advanced, and present information in an order and format that makes sense for that user. Whether it’s installing the tool, using the tool, contributing to the project or documenting cool things people have done with the project – organizing and presenting information about the tool is a different skill set than writing the tool itself.
Open Source Docs Press aims to engage technical writers to improve documentation for popular or requested open source projects.