GitBook is a documentation platform that helps you create beautiful docs for your users — with Git Sync built in. We see a lot of teams and projects building their own docs platforms, or documenting exclusively in GitHub. While those things can be great, we think there’s a better way.

What is Git Sync, you ask? Essentially, it lets you sync your GitBook docs with GitHub. Which means contributors can make changes from a repository by opening a PR, and those changes appear in GitBook, ready for you to review and merge. And of course, your published docs look great.

Sounds good, right? Now the only tough part is encouraging contributors to write great docs updates for your project.

To make that particular challenge a little easier, we’ve put together a few quick tips below that might help.

If you have any questions, come join me at the GitBook booth October 28-29th where I’ll be happy to answer them!

Cheers,
Addison Schultz
Developer Relations

---

7 things you can do to make it easier for contributors to write docs for your OSS project

We all know that documentation is important. For many people coming across your project, they’re 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.

1. Make your docs easy to browse and edit

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 sync your docs in GitHub with GitBook, you could move all your docs into their own repo and set up Git Sync to lay them out nicely and organize them into pages and groups.

2. Proactively open issues for your docs

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.

3. Triage your issues (regularly)

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 the code. Then make sure your issues are actionable and contain all the details 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.

4. Add tags to encourage newbies

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.

5. Write contribution guidelines specifically for your docs

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.

 6. Encourage them to write guides

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.

7. Say a public thank you

It goes without saying, right? Well yes, but actually you should also say it, because everyone loves a public shoutout and it’ll encourage your contributors to keep up their amazing work. It could be shoutouts in a PR or full release, or even thanking them in a dedicated social post or blog post. Whatever format works for you, thanking people in public is great for everyone.

Build unbeatable documentation for your open source project

Like we said above, GitBook can take everything you’re already doing with your docs and make it look even better. And best of all, you can do it all without paying a penny using a Free account and our Sponsored site plan.

With Git Sync, you can bring your docs and codebase together. So your users can edit docs in PRs in GitHub, and you can review and merge them in GitBook — with an intuitive UI for proofing, editing and approving changes. And Git Sync is included on all our plans, including the free plan.

Plus, GitBook supports Markdown, so when you import your docs they’ll already look great. And you can make them even better with customization options to add any branding you want. Plus you get built-in analytics, 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.

If you want, you can choose to publish your docs using our free Sponsored site plan. It includes everything mentioned above, 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.

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.

Anyway, enough about us. We hope these tips helped, and we hope to see you ATO on October 28–29th. In the meantime, happy documenting!

Want to know more about GitBook before the event? Head over to our website at gitbook.com/open-source.

---

The Featured Blog Posts series highlights posts from partners and members of the All Things Open community leading up to ATO 2024.