How to encourage contributions to your open source documentation
7 things you can do to make it easier for contributors to write docs for your OSS project
Last updated
7 things you can do to make it easier for contributors to write docs for your OSS project
Last updated
For many people coming across your open source project, your docs are the first port of call when they’re trying to work out whether to use it. But documentation is also often the most neglected part of an open source project. And that’s fair, because documentation can be hard to maintain.
That’s why writing documentation can be one of the most valuable ways to contribute to a project. And with the right set-up and guidelines — and with a great docs platform to help — it can also be a super simple process.
With all that in mind, here are a few ways you can make documenting a project easier, and encourage more people to do it.
This one probably seems obvious, and yet we still sometimes find projects with all their documentation in a single README.md file. Consider separating topics out into different files to make it easier to browse and find the information you need.
And if you did want to , you could move all your docs into their own repo and set up to lay them out nicely and organize them into pages and groups.
It’s important to check through your existing docs content regularly to spot outdated information, obsolete sections, or missing knowledge. But don’t jump in and try to solve all the problems you find right away. Instead, open an issue for each one.
Once you’ve opened issues for everything, you should fix only the ones that are going to be a barrier to new contributors. Things like deleting obsolete content or adding more section heading to make everything more readable. The main goal here is to make it as easy as possible for newcomers to edit your docs without getting blocked or confused.
Just like you would with code issues, it’s time for triage. Make sure the issues you’ve flagged are specifically related to your docs, and aren’t an issue that could be solved in your product’s code. Then make sure your issues are actionable and contain all the detail people need to fix them. Finally, assign a priority label to each one to help your contributors understand which ones are most urgent and which can wait.
One great way to encourage new contributors to your project is to add a specific tag, such as quick fix or first issue. This will flag those issues as a good starting point for newcomers to get up to speed with your processes.
You probably already have contribution guidelines for your code. They may even contain specific guidelines for your documentation! If you don’t, now’s a good time to create or update them. As your project grows, so will your documentation — so it might even be worth splitting out the docs’ guidelines out into their own document to make them easier to browse.
Could your docs be improved with guides on specific subjects that come up a lot with your users? Consider asking contributors to write them for you. You could get them started by creating the file or page and writing a rough outline of the process. Then you could ask contributors to flesh out your basic skeleton with more detail and screenshots.
It’s easy to think that everyone knows how grateful you are for their contributions. But it’s still important to acknowledge people’s hard work in contributing to your docs — because everyone loves a public shoutout, and because it’ll encourage your contributors to keep doing an amazing job. It could be a quick @ tag in a PR or full release, or even thanking them in a dedicate social post or blog post. Whatever format works for you, thanking people in public is great for everyone.
As we said above, GitBook can take everything you’re already doing with your existing docs, put it into a slick design, and make the editing process a breeze. And best of all, you can do it all without paying a penny — by signing up for a Free account and publishing your site with our free Sponsored site plan.
If you want, you can choose to publish your docs using our free Sponsored site plan. It includes everything mentioned above, along with free hosting and more. The free site puts a small, relevant ad in the corner of your project’s docs — and every view will earn you money. And GitBook doesn’t take a penny of that money, so you can use it to fund ongoing work on your project.
Most importantly, we believe strongly in ethical advertising. So we guarantee that the ads in your docs will never track or retarget your users.
Don’t want ads in your docs? Then choose from one of our other plans — including free and paid options — and get precisely the features you want.
It all comes back to our commitment to support open source. It’s where we started as a company, and open source software is still at the foundations of our platform — and close to our hearts.
→ Find out more about our plans for open source projects
With , you can bring your docs and codebase together. So your users can continue to contribute to your docs in PRs in GitHub, and you can review and merge the branches in GitBook — with an intuitive UI for proofing, editing and approving changes. And Git Sync is included in all our plans, including the Free plan.
Plus, GitBook supports Markdown, so when you import your existing docs they’ll already look great. You’ll get a dedicated docs site, and can make it even better with to add any branding and custom domain you want. Plus you get , so you can see how many people are viewing your docs, what they’re searching for, and how highly they rate each page — which is ideal when you want to find and fix problem areas.
