Too many open source projects suffer from inadequate documentation, and that hurts their adoption, their communities, and puts more burden on maintainers. Many people who create open source software don’t see see themselves as writers, but today I’m sharing tips for documenting open source projects without it needing to take up a huge amount of time to get something published and ready for (docs) contributions.

It seems obvious, but start with your README file – and if you have an existing file, really look at it from the point of view of a new user. Does it still contain the content from the template repository or code generator that this projected was started from? Feel free to throw it away and start again!

Key facts

• What would I use this project for?
• What does it not do?
• Are there platform requirements?

If you can answer these questions in the first paragraph, you’re serving even the most casual visitors in the best possible and “hooking” the people who are in the right place. If you have ascii art, those counter/status badges, a video or anything else – put this paragraph first even if you want to keep those other things.

For bonus points: set the topics and description for your project. These are shown at the top of the page and show up in search results when repositories are listed.

Quick start

For users who are already experienced with the tech stack and concepts covered by your tool, they might not need much help to onboard. Add a section for these impatient individuals with quick installation instructions, and a couple of realistic usage commands that will work when copied/pasted.

Installation

For normal users, take a more stepwise approach to explaining the platform requirements, any dependencies, and how to install the tool. Remember that not every user might use your tech stack, so mentioning which dependency management tool to use, and showing the command(s) for installation, can help. Far more people can use your tool than can write the code for it – but the majority of tools should be usable by any technical person. This section makes that actually true.

Usage

The “help” output of your CLI tool can be a useful thing to include, but by itself it is not documentation.
You should also include one or two sentences for each of a handful of common tasks, and then code examples of how to achieve those tasks. You can probably harvest some of this content from your answered issues list. It serves two purposes: one is the usage documentation that is the expected use, but the examples you pick here also illustrate the main purposes of the tool and help users to understand if this thing meets the needs that brought them to your page.

If you have a lot of functionality or complicated usage, move the details to another page or directory and link to it. Similarly if you start a section like this and it just gets really long over time. It’s an excellent problem, put everything in a one-section-per-markdown-file format in a folder called docs/ and link to it. Perhaps you’ll publish a docs site one day, perhaps you won’t, but the simple approaches serve your technical audience well without causing a lot of extra work.

More key information

If your tool has a lot of configuration, requires templates, or has a lot of integrations available – add a section for those main topics here. Again, the issues list (including closed issues) on an established project will give a good sense of what users get tripped up on and where to start. If the information is already available elsewhere then link to it. The same points about putting markdown files in a docs folder to separate topics will help you here.

Contributing file

If your project allows (or encourages!) contributions, say so. From the README file, link to the CONTRIBUTING file. In there, spell out whether contributions are welcome, if there are any requirements around issues, branch naming, license agreements, or anything else. You might already have this information in the README, in which case move it over.

Tell users how to build/run the project from the source code in the respository, how to run the tests, what formatting rules are used – anything else that will help make a pull request closer to acceptable on the first attempt, because those small things save time and effort for both contributors and maintainers.

Call to action

Can users contact you? Open an issue? Join a group? Help in some way? Support the project? Tell them!

Summary: Just enough docs

Start with a good README, clear getting started instructions, and some key usage points, and you won’t go far wrong. Encourage users to open pull requests to update the pages in the project if you answer a question for them, and soon you’ll have a documentation culture you can be proud of. Documentation is one of the most valuable and transferable skills for developers too, so it’s very much worth your time and effort personally as well as for the project.