Every year, GitHub conducts research and releases its State of the Octoverse report, identifying trends in developer experience among software development companies and open-source projects. This year, the research incorporated telemetry data from over 4 million repositories (including many from paid GitHub Team or Enterprise Cloud accounts) and direct survey responses from over 12,000 developers.
In addition to its general findings, GitHub’s report includes deep-dive investigations into several focus areas that vary each year. The 2021 report takes an in-depth look at these:
- Writing and shipping code faster
- Creating documentation to support developers
- Supporting sustainable communities
It also includes predictive models in each of these areas to help organizations identify the actions they can take to achieve success.
Needless to say, we at Swimm were pleased to see documentation finally get its turn in the spotlight, and we found the takeaways in this area particularly meaningful. We were also especially interested in the findings related to developer productivity and mentorship/team culture in the other areas of the report.
Why does it matter?
At the end of the day, GitHub’s State of the Octoverse is concerned with improving developer experience: working habits, productivity, and overall career satisfaction. And developer experience has never been more important than in our current reality – marked by a global tech talent shortage and pandemic-engendered remote/hybrid working environments.
So, let’s take a closer look at the research and apply its findings to optimize developer experience and make our organizations and development teams the best they can be.
Key takeaways from the report
We’ll start with key takeaways from the Creating Documentation section of the report, then we’ll turn to key findings in some other areas on which documentation has a particularly strong bearing.
Documentation matters
In both open source projects and enterprises, developers see about 50% productivity boost with easy-to-source documentation.
When my co-founders and I started Swimm in 2019, we understood the value of good documentation to the software development cycle and its critical importance to the process of onboarding new developers. We also recognized that, despite universal industry acknowledgment of its value, good documentation was significantly underutilized and under-invested.
GitHub’s 2021 Octoverse report confirms what we’ve known all along: Documentation matters. Big time.
A 50% productivity increase for developers with access to good documentation confirms that it’s not just a “nice to have.” Documentation is a game changer.
What constitutes good documentation
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.
The report goes on to suggest that enterprises can adopt some of the best practices used by open source projects (such as READMEs, contribution guidelines, and GitHub Issues) to achieve similar success in project quality and information sharing. The productivity boost offered by strong documentation is achieved when documentation is up to date, detailed, reliable, and comes in different formats (for example, articles, videos, forums).
While producing this level of documentation and keeping it up to date may sound like an unachievable goal, we at Swimm set out to make it possible, and scalable. And that’s exactly what we’ve done (and we’re making it better every day!)
- Swimm’s code-coupled editor makes it easy to create documents with embedded live code snippets, enables fluid editing without the need to take your hands off the keyboard.
- Our IDE integrations allows you to open Swimm’s code-coupled documentation right inside your IDE.
- Swimm Playlists collect documents, images, videos, markdown files, and links that allow the reader to progress through each collection in the most effective order.
- Auto-sync and Git Checks ensure that any documentation pushed to Git stays up to date by alerting you when the code reference in the documentation has changed. And with Smart Text and Tokens, Swimm can even make changes for you to ensure your documentation is always up to date.
Check out Swimm’s free demo to experience all the benefits of Continuous Documentation for yourself.
Making the conventions of a project understood facilitates building on each other’s work
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.
The concept of frictionless contribution and code reuse dovetails nicely with a key takeaway from the Writing code faster section of the 2021 State of the Octoverse, which reports that developers’ performance at work can increase by up to 87% when reusing others’ code is easy and doesn’t introduce friction.
In addition to providing documentation, software development organizations and open-source projects can make code reuse frictionless by removing or minimizing barriers. Streamlining entitlement procedures and lengthy access approvals, remedying poor indexing, and eliminating undocumented dependencies all contribute to easy-to-reuse code and, consequently, to empowered developers and improved software delivery performance.
Ease of search is underestimated
Developers are almost 60% more likely to feel equipped to do their job when they can easily find what they need. Plus, they can get an 11% productivity bump simply by having a team repo that is easy to search – a finding supported by earlier research as well.
Another documentation-related takeaway from the Writing code faster section of the report has to do with ease of search. The report explains that searchability is a product not only of an efficient search algorithm but also of consistent code standards and naming conventions.
How are these standards and conventions communicated throughout the team? Through the creation and maintenance of good documentation, of course, and IDE integration where you can see – in real time – what is documented with Swimm.
The shift to hybrid or fully remote work environments makes adopting the right tools to support efficient collaboration more important than ever
Development work is all about collaboration – with the right tools.
It’s no surprise that GitHub’s 2021 survey shows ongoing changes to where we get work done. Responses from over 12,000 developers indicate the following trend for those working in companies:
- Prior to the pandemic: 46% of respondents reported that they worked in collocated environments in which all team members worked in an office all or part of the time.
- After the pandemic: Instead of working in a collocated environment, 26% expect to work in a hybrid environment in which some team members work in an office and others work remotely. 20% expect to work in a fully remote environment in which all team members work remotely.
What does this mean for collaboration? Of course, we’ve recognized the need for increased use of real-time communication tools such as Zoom, Slack, and Teams. These tools can bring us closer to approximating “around-the-water-cooler” brainstorming and “over-the-shoulder” knowledge transfer and collaboration.
At the same time, the need for asynchronous communication tools and long-term knowledge sharing is greater than ever – once again underscoring the importance of internal technical documentation and the right tools to make creating and maintaining it practical and less painful (even if not 100% painless).
This brings us to our final takeaway, which pulls together key findings from the Creating documentation and Sustainable communities sections of GitHub’s 2021 State of the Octoverse…
Good information flow and mentorship support strong cultures, increased productivity, and developer satisfaction
Documentation is good for productivity and culture – it’s a win-win.
When it comes to building strong cultures, metrics uncovered by GitHub’s research into creating sustainable communities are particularly telling:
- Trust: Teams with high trust are more likely to have a healthy collaborative culture – 2x more likely in companies, 3x more likely in open source. While the relationship between trust and collaboration is not surprising in and of itself, the extent of the relationship is striking.
- Mentorship: Explicitly providing mentorship almost triples the chances of an open-source team having a healthy culture and a sense of community belonging. In work settings, mentorship almost doubles the likelihood of a strong culture. How does this translate to productivity? A commitment to mentorship leads to a productivity increase of 46% in open-source projects and 16% in companies.
But the realities of 2022 once again bring the challenge presented by these metrics to the fore: How do we build trust within geographically dispersed teams? How do we mentor new team members from a distance? And, lest we get too caught up in the challenges engendered by the pandemic, let’s not forget that a global tech talent shortage has forced many organizations to bring on entire teams from halfway around the globe.
A big part of the answer takes us right back around to documentation and GitHub’s conclusion that strong cultures built on trust are supported by good information flow. When we can’t provide mentorship from within the same room (or city, or country, or hemisphere), we must create onboarding experiences that take our new team members by the hand and lead them through the codebase. Good documentation, remote learning, and the tools that make these possible go a long way towards getting this done.
Bottom line
GitHub’s 2021 State of the Octoverse provides invaluable insights into improving developer experience, increasing productivity, and building stronger software development organizations. Many of the key takeaways underscore what we’ve known all along: Documentation truly is a game changer. We hope you’ll take the time to further explore the data and read the full report. Or you can download a 2-page snapshot if you want the abridged version!
We also invite you to join Swimm’s growing developer community and learn more about making documentation a game changer that wins the game for you.
