Documentation as a Pillar in Developers Coding Experience

New TCIO June 14 2021 (3).png

Documentation gives the information about projects, and it informs a contributor or user on what is active and what is healthy or what shouldn't be tampered with. Keeping documentation up to date is also a good practice to adopt because this will inform any new person about the latest changes in the project.

    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."

    Work model. Source: Work model. Source:
    Open source model. Source: Open source model. Source:

    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.


    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.

    Get similar stories in your inbox weekly, for free

    Share this story:
    The Chief I/O

    The team behind this website. We help IT leaders, decision-makers and IT professionals understand topics like Distributed Computing, AIOps & Cloud Native

    Latest stories

    How ManageEngine Applications Manager Can Help Overcome Challenges In Kubernetes Monitoring

    We tested ManageEngine Applications Manager to monitor different Kubernetes clusters. This post shares our review …

    AIOps with Site24x7: Maximizing Efficiency at an Affordable Cost

    In this post we'll dive deep into integrating AIOps in your business suing Site24x7 to …

    A Review of Zoho ManageEngine

    Zoho Corp., formerly known as AdventNet Inc., has established itself as a major player in …

    Should I learn Java in 2023? A Practical Guide

    Java is one of the most widely used programming languages in the world. It has …

    The fastest way to ramp up on DevOps

    You probably have been thinking of moving to DevOps or learning DevOps as a beginner. …

    Why You Need a Blockchain Node Provider

    In this article, we briefly cover the concept of blockchain nodes provider and explain why …

    Top 5 Virtual desktop Provides in 2022

    Here are the top 5 virtual desktop providers who offer a range of benefits such …

    Why Your Business Should Connect Directly To Your Cloud

    Today, companies make the most use of cloud technology regardless of their size and sector. …

    7 Must-Watch DevSecOps Videos

    Security is a crucial part of application development and DevSecOps makes it easy and continuous.The …