It’s thrilling for open tasks to develop from a handful of customers to a workforce of collaborators engaged on and utilizing the software program. Transferring from one to many contributors is a robust second for any venture. Nevertheless, as a venture scales and grows, one space is ceaselessly uncared for: the documentation.
Lacking or inadequate documentation hinders a venture’s capability to scale. Most potential customers skim your documentation first to see if it matches their wants and to evaluate how troublesome it could be to make use of. Documentation makes your venture’s first impression: not solely on potential customers, but in addition on potential contributors.
Writing and enhancing documentation affords a transparent path for individuals to contribute to your venture—supplied you supply the suitable steering and processes to help them. This text covers greatest practices for attracting and retaining open-source documentation contributors based mostly on our expertise constructing and managing documentation for Kubernetes.
Consider your current docs
Start by evaluating your current documentation. You’ll be able to’t ask for assist out of your contributors in the event you don’t know what you want! As you consider your documentation, think about it from the angle of your customers:
- What are my customers’ wants? Do these docs meet their wants?
- Are there any options which can be undocumented? Is vital data lacking? Are there different content material gaps to fill?
- What content material is outdated and must be deleted?
- What content material must be refactored and clarified?
Don’t get slowed down making an attempt to repair every difficulty you come throughout. As a substitute, open a problem for every downside you encounter.
When you’ve evaluated your content material, overview the problems you opened and decide whether or not it’s worthwhile to repair any points earlier than you invite contributors to deal with them. For instance, in case your documentation consists of a single-page `README.md` file with 2,500 traces, breaking it up into smaller particular person paperwork will decrease the barrier for contributors. In case your documentation comprises outdated content material, delete it in order that new contributors can be a part of extra simply. Repair any points you suppose would block new contributors from working in your content material.
Triage your doc points
A easy doc difficulty triage course of may look one thing like this:
Now that you’ve a set of points associated to your documentation, apply triage. Triaging documentation points is much like triaging code points: be sure a problem is legitimate and actionable and assign a precedence.
- Validate if the problem is expounded to your documentation and never associated to your code: It’s widespread for a problem to be associated to each. Contemplate whether or not new documentation or a code change would assist your customers extra. For instance, if a CLI command has a complicated title, you can both doc the command higher or rename the command to one thing clearer.
- Assess whether or not the problem is actionable: Does the problem comprise the whole lot a contributor wants with a view to repair the issue? Tag unclear points with one thing like `wants extra data` and comply with up with the one that filed the problem. For instance, a problem that reads solely, “This didn’t work,” with out specifying what didn’t work or repair it isn’t actionable.
- Assign a precedence to the problem: What does the venture want to repair first? You should use a precedence numbering system (like P0-P4) or specify your priorities with tags like `now`,`subsequent`, and `backlog`.
Lastly, for brand new contributors, tag points which can be fast fixes or good first points. A label like `good first difficulty` makes it straightforward for brand new contributors to determine points they will tackle after they’re getting began together with your venture.
Kubernetes makes use of a doc difficulty triage course of similar to the one listed above.
Add documentation processes to your contributor tips
Hopefully, you have already got contributor tips (if not, GitHub has nice steering you possibly can comply with in setting them out). In your tips, embody steering particular to documentation, together with:
- How documentation is written and served: Point out which markup language(s) you’re utilizing, any documentation templates you’re utilizing, and whether or not you’re utilizing any instruments like static web site mills to show your content material.
- How documentation is organized: Give clear steering on what kinds of content material belong the place, together with how information and folders are organized. Specify which sorts of content material belong in product documentation and what content material could be higher suited to Stack Overflow or your venture’s weblog.
- Any documentation requirements: Specify any naming conventions you’re utilizing in your documentation. You’ll be able to preempt a excessive quantity of questions out of your contributors about grammar, capitalization, and punctuation by following a public type information. Each Google and Microsoft present public documentation type guides.
- Particular steering for docs change requests: Present clear steering for the contribution course of. For instance, specify branches on which to open change requests, any tags wanted for documentation PRs, and any further overview processes required for documentation.
- Reply contributors’ most typical questions: When you end up repeatedly answering the identical contribution query, add that query (and its reply) to the contribution information.
For Kubernetes, we created a basic documentation contribution information and steering for submitting a docs PR.
Make it straightforward (and enjoyable) in your contributors
By offering a transparent set of triaged points and tips for contributors to comply with, you possibly can scale up your variety of contributors. Keep in mind that like code, the processes you’ve created for docs want common overview and upkeep. Evaluate your points repeatedly to triage them and take away any that change into stale or outdated.
Likewise, set an everyday cadence for reviewing documentation PRs. Editdocumentation PRs each for editorial and technical high quality and provides your contributors well timed and pleasant suggestions.
Lastly, acknowledge the contributors to your documentation. You don’t must do something as grand because the open-source peer bonus program. Thanking contributors of their PRs, saying their names when doing a launch, and publicly thanking them for his or her work on a venture’s weblog can go an extended approach to exhibiting your gratitude.
Jared Bhatti and Zachary Sarah Corleissen are Emeritus SIG-Docs Committee members of Kubernetes, and not too long ago co-authored the e book Docs for Builders: An Engineer’s Subject Information to Technical Writing.
Tags: neighborhood, documentation, open supply
