Creating documentation to support developers
No matter the format, documentation is important
Building on top of others’ work in a community-like way can be an accelerator, both in open source and in companies. Documentation often signals if a repository is reliable to reuse code from, or if it’s an active project to contribute to. What signs do developers look for?
In both open source projects and enterprises, developers see about
productivity boost with easy-to-source documentation
What the data shows: At work, developers consider documentation trustworthy when it is up-to-date (e.g., looking at time-stamps) and has a high number of upvotes from others. Open source projects use READMEs, contribution guidelines, and GitHub Issues, to elevate the quality of any project, and to share information that makes them more attractive to new contributors. Enterprises can adopt the same best practices to achieve similar success.
In both environments, developers see about a 50% productivity boost when documentation is up-to-date, detailed, reliable, and comes in different formats (e.g. articles, videos, forums).
Using the data: Review the documentation your team consumes: When was the last time it was updated? Can everyone on your team improve the documentation? Check this frequently to stay on track.
Documentation is critical but often under-invested
Documentation is often an under-resourced area of projects, despite being critical to onboarding new contributors, improving the quality of work, and creating shared understanding.
What the data shows: Sharing and sourcing knowledge through different forms of documentation improves productivity both in open source projects and at work. Internal documentation covered onboarding, governance, tutorials, structure/dependencies, and best coding practices.
Using the data: Use these charts to identify one thing you can work on to improve your work! Pick something on the bottom (at the end of an arrow), then work backwards to see what has a significant effect. For more details about each construct, head to the companion repository for the survey items we used.
Improving productivity with documentation
Each box in the model is a construct (either a practice of development work, documentation, or healthy communities; or outcome of doing these things well). Each line is a predictive relationship between constructs. When you see a line, you can generally read it as “predicts” or “affects”. Colored lines are positive relationships, and gray lines are negative. For this particular section the model did not show any negative relationships (hence, no gray lines).
Rules of engagement remove ambiguity and friction
When companies work closely with open source communities, making the conventions of a project clearly understood facilitates building on each others’ work.
What the data shows: Contribution guidelines have gained traction as “rules of engagement” when creating enterprise-level open source software. Repositories that are used for both open source and work are 4.4x more likely to have contribution guidelines than other repositories.
Using the data: Add contribution guidelines to your repository if you don’t have some already. These have the added benefit of making code frictionless and easy to use.
Repositories used in both work and open source are
more likely to have contribution guidelines as other repositories
Why would a company want to add contribution guidelines to its repository? When developers know how to contribute to a repository that belongs to a different team or community, it removes ambiguity and friction, and they are 17% more productive.
Number of repositories with and without contributor guidelines by repository type
(1,101,035)
(67,115)
(78,752)
(25,203)
(2,543,399)
(149,873)
README-- or not?
Open source repositories often use READMEs to share information and to signal that a community is active.
Number of repositories with and without README, by repository type
(33,544)
(204,373)
(6,000)
(42,954)
(796,235)
(147,975)
What the data shows: Our analysis found that work repositories use READMEs considerably less than open source projects, but this could be because they share documentation and information in other internal forums or methods, as well as using pairing or onboarding buddies for knowledge transfer.
Using the data: Try incorporating a README to your repository to keep essential information close to the code.
GitHub Issues are documentation too
Another way to share information about a project is through GitHub Issues.
What the data shows: Creating issues is the most common first contribution, and invites non-code contributors. This provides a great way for people to join GitHub and help manage projects.
Using the data: Think about your own projects and new team members: Can folks jump in to projects by creating issues easily?
What people do on their first hour on GitHub
Good First Issues guide new member contributions
What the data shows: Marking issues as Good First Issues is a great way to guide new members to their first contribution. Large repositories are generally more likely to use Good First Issue labels, and it’s an effective practice. Repositories where 21% to 30% of issues are marked as Good First Issues average 13% new contributors. Having more than 40% Good First Issues can help a project attract 21% more new contributors.
Using the data: Think about your projects again. Are there more ways to get involved beyond issues? What tasks do you typically give new team members to start with? Start curating a set of tasks/issues that are appropriate for new folks to start with when joining your project, team, or community.
Percentage of new contributors by whether repository has any “Good First Issues”
Accounts < 2 years old
Percent of issues with “Good First Issue” label
Accounts < 2 years old
Is the average of new contributors for repositories where 21% to 30% of issues are marked as Good First Issues
Documentation is good for productivity and culture -- it’s a win-win
Strong cultures built on trust are supported by good information flow, and recent research by DORA shows that quality documentation improves performance.
So it shouldn’t be a surprise that good documentation practices some examples here support not only better cultures where developers feel fulfilled but also help them do their work.