How to Document a Project

Originally appeared on the Orchestrate Blog

July 28, 2014

Share +

Last time, we covered how and why to write readmes worth reading, which focused on writing documentation for new users of your software. This time, we’ll cover best practices for documenting projects for teams, collaborators, and volunteers.

First, why should you document your project at all? You’ve already got a good readme, so what else is there? Readmes are good entry points for users and consumers, but folks contributing code to your project need more information to collaborate effectively. It’s not enough that a contributor know how to use the library. They need to understand how the code they contribute will be judged and scrutinized. Folks new at programming will want direction when you won’t have the time to give it, even though their added effort will be critical to the project’s growth and success.

The bottom line is, at some point, other humans will want to modify your code. Project documentation makes that painless for all involved.

So, how does one write good docs?

List Resources

First, make clear where to find anything related to collaboration. Like what?

How to find tasks good for new contributors, like simple bugs, documentation errors, bad tests. For folks who want to help but don’t know where to start, such as folks new to open source, these practices are invaluable.

How to communicate with the project’s maintainers and other contributors. Do you have an IRC channel? Email list? Backup internet powered by pigeons? List where to find these resources, and what they’re used for.

How to file bugs, issues, and feature requests. How should folks let the team know something broke, or isn’t up to snuff?

How to contribute code. If you use GitHub, do you use the Big Green Merge Button? Do pull requests require a +1, consensus, or the favor of the stars?

How to set up your development environment for contributing to the project. (This may be very different from normal installation, so highlight any differences)

How contributors should indicate their involvement. Whether your project uses an AUTHORS file or the contributors field of package.json to list folks who have written code for it, point it out, and let folks know to add themselves, to recognize their effort.

Python Requests’ contributors section handles most of these up front, and the project’s issues and pull requests demonstrate a vibrant discourse evaluating problems and solutions. But, once you’ve listed resources, how do you make sure they’re used properly?

How do you make sure contributions don’t… suck?

Set Expectations

The first step to creating a safe space is to lay ground rules. Let folks know what’s acceptable, what’s not, and then enforce it. This is common practice in social justice, and as a trans woman it makes the difference for what events and committees I will and won’t attend and condone. It’s the same in programming: set expectations, and everyone will be happier.

When folks come on to a project, whether as volunteers or employees, let folks know not just where to find things, but what’s expected of their contributions and of them as contributors.

For code contributions, are tests required?

What are the project’s style and whitespace norms?

How does the project team make decisions?

What constitutes a minor version change, or a major one?

Whose responsibility is it to update the readme or API reference when features change?

Node.js’s Contributing for Dummies walks newcomers through every last step of submitting a code change for review, and sets expectations about the difficulty of getting code through review:

Don’t get discouraged. Node is held to high standards, and it can take months to begin to feel comfortable with how the workflow operates and why things are done the way they are. Jump on IRC. Chances are someone is there ready to help.

Statements like “Don’t get discouraged” illustrate the priorities of your project, and how you value the people working on and using the code relative to the code itself. Setting expectations is as much about helping contributors write better code as it is about helping people treat one another right. For bad examples, see Linus Torvalds, all the time.

Sounds like a lot of work…

As your project’s community grows, the primary function of documentation shifts from on boarding contributors to community management. High-quality project documentation will help your community grow faster, but will also be unnecessary until your community gains traction. If your team is you and a close buddy, you probably won’t need to spend a lot of time talking about structuring community norms to maximize contributions and prevent burnouts. But if you want your project to grow beyond you and your buddy, you’ll need to put in the time to make coming aboard not merely effortless, but joyous.