Documentation as a Pillar in Developers Coding Experience

Documentation is as important in development as the code used in the building of the project.

Especially when you now need to determine what the project is about if it's a code you can reuse or a project you can be a contributor to. Documentation is what developers mostly look for when trying to know about a project, and they always have a sense of trustworthiness towards the documentation when it is an up-to-date one. On GitHub, documentation for open source projects always comes as READMEs, contribution guidelines, and GitHub issues. And this practice of documentation is made to share information to attract contributors and elevate project quality.

This mode of documentation is a practice enterprises too can incorporate to have the same result.

Investing in documentation

Documentation of projects is the most unattended-to section in development. Whereas documentation is the best shot for new contributors of a project to get started, and documentation is a practice that will bring first-hand quality improvement to any project while also posing as shared knowledge of the project.

GitHub survey data shows that using documentation to share or source for knowledge improves productivity in both open source and work projects.

According to the State of Octoverse report, GitHub came up with a model based on the survey data for this year to understand what makes developers and teams perform better, be more productive, and have excellent development experience.

The models are constructed to represent development work practices, documentations, healthy communities, or the outcome of successfully completing these processes.

The models show you what will be the result (end of the arrow) of doing some practices.

Each line of the arrow shows the prediction or effect of the practices stated. The colored lines indicate a positive relationship between practices and effects, while the grey ones show negative relationships.

The model is in two-phase, the "work model" and the "open source model."

Reduce friction with contribution guidelines

When creating enterprise-level open source software, stating clearly the conventions of the project boosts building on the previously built work. Rules of engagement are popularly known as contribution guidelines in enterprise-level open source developments. GitHub data shows a 4.4x possibility for a repository used for open source and work to have contribution guidelines.

GitHub telemetry data shows that 94.25% of open source projects repositories don't have contributor guidelines, while just 5.75% have contributor guidelines. 75.76% of the open source at work project repositories don't have contributor guidelines, while 24.24% have contributor guidelines. Then 5.56% of work project repositories have contributor guidelines, while 94.44% do not have contributor guidelines.

README

This is essentially the tool used in inviting members to open source projects because it basically tells information about the project. Open source projects use README considerably more than work projects. The best guess of why that is is that documentation probably gets distributed during internal meetings or forums, or a pairing method is used for knowledge transfer.

GitHub telemetry data shows that 14.1% of open source projects repositories don't have READMEs, while 85.9% have READMEs. 12.26% of the open source at work project repositories don't have READMEs, while 87.74% have README. Then 15.67% of work project repositories have README, while 84.33% do not have README

GitHub issues equals documentation.

Issues creating is the first thing most people do in their first hour on GitHub, thereby sharing information about a project.

Creating issues invites non-code contributors, but it helps in making project managers come forth. GitHub data shows that 192,830 people create issues on their first hour on GitHub, followed by 60,854 people that comment on issues, 24,404 people push on their first hour, 16,102 people create a pull request, 2,575 people comments on a commit, and 1,053 people reviews a pull request.

New members get help from Good First Issues.

Good First Issue is more like a list of easy issues that new contributors can pick to make their first contribution. Doing this increases the confidence and experience of contributors over time. This initiative is used mostly by large repositories to get more contributors. Averagely, there's always about 13% new contributors to a repo with 21% - 30% Good First Issues, and 21% of new contributors to repo with more than 40% of Good First Issue.

Productivity and culture come as a result of good documentation. Performance improvement and cultures built on trust are achieved through smooth and accurate information flow.