How to write documentation for an open-source project

Most open-source projects start with a README, and for a while that's enough. Then people start using the project. Someone wants to run it behind Nginx, someone's config stops working after an upgrade, and someone who wanted to send a fix gives up because the tests won't run on their machine. The answers end up in issue comments, chat threads and the heads of one or two maintainers, and the same questions keep coming back.

This guide covers how to get that knowledge written down where people will look for it: what the README should and shouldn't do, which pages to write first, how to help new contributors, and how to keep the docs from falling behind your releases.

Keep the README short

A README has two jobs. It helps someone decide whether the project is what they're looking for, and it gets them to a first working run. When it tries to do more than that it gets long, people skim it, and the important parts get lost in the middle.

A README that does its job usually has:

• A sentence or two on what the project does and who it's for
• A screenshot or a short code example
• The quickest way to install it and try it
• Links to the docs, the contributing guide and where to ask for help
• The licence

Everything else goes in the docs: the full list of configuration options, upgrade notes for each version, deployment guides, and the FAQ that grows a little every month. A quick test is to ask whether a section matters to someone who hasn't installed the project yet. If it doesn't, move it.

Pick one home for the docs

There are three common options, and each suits a different kind of project.

• A docs folder in the repository, built into a site with a static site generator. Docs changes go through the same pull requests as the code, which helps keep them accurate. The cost is a build and a host to look after, and anyone who wants to fix a typo needs to know Git.
• The repository's wiki. It's quick to start but gets hard to organise as it grows, and changes aren't reviewed like code. On GitHub, search engines only index a wiki if the repository has 500 or more stars and the wiki doesn't allow public editing, so most project wikis never show up in search results.
• A hosted documentation tool. There's no build to maintain, and you get an editor, search and private pages without setting anything up. Changes don't go through pull requests, so you need a habit that keeps the docs in step with the code. There's one further down.

Whichever you pick, keep everything in one place. If half the docs are in the wiki and half are in a docs folder, people have to check both, and most won't.

Write for someone who has just installed it

Most people reading your docs have just installed the project and want to get something working. Write for them before anyone else. The architecture overview can wait.

These are the pages most projects need, roughly in the order to write them:

1. Getting started. How to install it, the smallest setup that works, and how to check it's working. Use commands people can copy, and say which versions you've tested with.
2. Configuration reference. Every option, its default and an example. A table works well. If an option exists in the code, it belongs on this page, even if you think nobody uses it.
3. Troubleshooting. The errors people actually report. Use the exact error message as the heading, because that's what people paste into a search box.
4. Upgrading. What changed between versions and what people need to do about it. There's more on this below.
5. FAQ. Wait until you've answered a question three times before adding it.

Self-hosted apps need a few more pages: system requirements, running behind a reverse proxy, backups and restores, and moving to a new server. Libraries need more examples. One short example for each common task is more useful than a complete API listing with none.

Your issue tracker is the best list of topics you'll get. Search closed issues for questions that come up again and again, and turn each one into a page or a section. The next time someone asks, reply with a link.

After each install step, say what people should see if it worked. Most install guides stop at the command, which leaves people unsure whether to carry on or start troubleshooting. One sentence fixes that.

For more on writing pages like this, see how to write documentation people actually use.

Make it easy to start contributing

People who want to contribute tend to get stuck in the same place: getting the project running on their own machine. A contributing guide that gets them past that point does more for your project than a long list of code style rules.

Cover these, with the exact commands where there are any:

• Setting up a development environment, from cloning the repository to a passing test run
• Running the tests, the linter and the formatter
• How the code is laid out, in a paragraph or two: where it starts and which folders matter
• What a good pull request looks like: how big, whether it needs tests, and whether to open an issue first
• Where to find good first issues
• How long reviews usually take, so nobody thinks they've been ignored

Test the setup steps on a clean machine or in a fresh container. Better still, ask your next new contributor to note every place they got stuck, then fix those steps.

Keep a CONTRIBUTING.md file in the repository even if the full guide lives on your docs site. GitHub shows a link to it when someone opens an issue or a pull request, so a short file that points to the full guide is enough.

Write down what only maintainers know

Some knowledge only matters to people with commit access: how to cut a release, who can get into the package registry and the domain, how to rotate a signing key, and what happens when a security report comes in. It rarely gets written down, because the people who know it never need to look it up. Then a maintainer steps back, and whoever's left has to piece the release process together from old CI logs.

This doesn't belong in the public docs, but it does need writing down. Keep it in a private space that only maintainers can see, and start with:

• A release checklist, step by step, including the parts CI doesn't do, like announcements and updating the docs
• Accounts and access: every account the project depends on and who can get into each one. Write down where credentials are kept, never the credentials themselves.
• Security reports: who handles them and what they do first
• Decisions: a short note for each big decision, covering what you chose, what else you looked at and why

Decision notes can often be public. When someone opens an issue asking why the project doesn't support X, you can link to the reasoning instead of writing it out again.

Make docs part of finishing a change

Docs fall behind when updating them is a job for later, because later doesn't come. Treat the docs as part of the change instead. If a pull request adds an option, renames a flag or changes a default, it isn't finished until the docs say so.

Add a line to your pull request template:

- [ ] Docs updated, or not needed because: ___

Asking for a reason stops people ticking the box out of habit. If your docs live outside the repository, ask for a link to the updated page in the pull request and check it as part of the review.

Write upgrade notes for every release

Release notes tell people what changed. Upgrade notes tell them what they have to do about it, and they're the ones that save you from a pile of new issues the week after a major release.

For any release that needs action, write down:

• What breaks if people upgrade and change nothing
• The exact change to make, shown before and after
• Whether people can skip versions or need to upgrade through each one
• How to roll back if something goes wrong

A before-and-after snippet answers most questions on its own:

# Before (2.x)
storage_path: /var/lib/larkspur

# After (3.0)
storage:
  path: /var/lib/larkspur

Plenty of people stay on an older major version for a long time, especially with self-hosted apps. Keep the docs for the previous version available, and make it obvious which version each page covers. Someone following 3.0 instructions on a 2.x install won't notice the mismatch. They'll open an issue saying it's broken.

Put the answer in front of people before they open an issue

A lot of issues are really support questions. You won't stop all of them, but you can put the answer in their way.

On GitHub, a config.yml file in .github/ISSUE_TEMPLATE adds links to the page people see when they click "New issue". Use it to send questions somewhere other than the issue tracker:

blank_issues_enabled: false
contact_links:
  - name: Read the troubleshooting guide
    url: https://docs.example.org/troubleshooting
    about: Fixes for the most common setup and upgrade problems.
  - name: Ask a question
    url: https://github.com/example/larkspur/discussions
    about: For help with setup and usage.

A few other places worth a link:

• Error messages. If your code knows what went wrong, it can point to the fix, like this: Unknown config key "storage_path". See https://docs.example.org/upgrading/v3
• Your chat's welcome message, if the project has a Discord or Matrix server
• Your replies. When you answer a question in an issue, ask whether the docs could have answered it. If they couldn't, update them, then close the issue with a link to the page.

If your docs tool shows what people search for, look through the list every month or so. A common search that few people click through from usually means a page is missing or has the wrong title.

A starting checklist

• Cut the README down to what the project is, how to try it and where the docs are
• Write a getting started page that says what people should see when it worked
• Start a configuration reference with every option and its default
• Turn the five questions you're asked most into troubleshooting entries
• Write a contributing guide and test the setup on a clean machine
• Add a docs line to your pull request template
• Write the release checklist in a private maintainer space
• Add docs links to your issue chooser and error messages

See how Docvora works for open-source projects, including private maintainer pages, your project's own domain and 50% off for open-source projects.