Introduction
In Part 1, we discussed the personal and human factors affecting all of us during the COVID-19 pandemic. In Part 2 of this series we talked about how a combination of cultural and technology factors has traditionally led to insufficient collaboration among developers. In Part 3 we discussed how transparency needs to turn into visibility in order to create team alignment and boost velocity and productivity. We turn now to documentation as a tool to improve remote developer performance.
Documentation has been a source of frustration and conflict in software development for many years. The problem is, fundamentally, that many developers don’t document their code, or do so poorly. As a result, other developers who need to understand the code they are utilizing or changing spend many frustrating hours addressing this shortcoming. Understanding code can take as much as 10X the amount of time as writing new code.
Why don’t developers document their code?
There are many examples of articles and posts that discuss this question. For instance, this article in Infoworld from 2012 asks “Why don't programmers document? Real programmers don't document is an old chestnut of hacker machismo, one that some coders have sadly taken to heart,” Infoworld states. Their answer might reflect a nugget of truth, but is by no means a universal explanation nor a solution. In a post in 2018 Tomer Ben Rachel argues that “The main reason code goes undocumented is because of time. When developing a feature that needs to be completed within a certain time frame, rarely do we have a moment to stop everything and focus on documenting our code.”
In an all-remote world, documentation is one more essential tool to sustain team alignment. This is a great moment to revisit how we think of documentation and its value. The good news is that there is a better way.
The dawn of On-Demand documentation
At CodeStream we have been working to improve internal documentation practices for over two years. Given that so many fast-moving organizations don’t produce much useful documentation, and that surveys show that less than 15% of developers use internally generated documentation in their work, we believe in on-demand documentation. What does this mean?
When a developer implements a new component or module, instead of trying to figure out in advance what others may not understand when they encounter the code in the future, CodeStream allows the developers using that code to more easily ask questions, and pull the information from the authors. We have implemented an in-editor interactive FAQ approach that captures the question and answer interaction and attaches it to the code it refers to. So not only do the missing pieces get filled in to solve the immediate need, the discussion is saved alongside the code for the benefit of the next developer who consumes the component or module.
Bringing it back to the IDE
Until now, information about your code that explains how it all works has been fragmented, spread out in a variety of different tools and systems. Finding the right information is quite time-consuming, and sometimes impossible. By tying it all back to the IDE and, specifically the code it refers to, documentation emerges as the byproduct of the interactions that take place every day among developers in Slack, Jira, GitHub and other systems. CodeStream inserts itself in the workflow to capture and organize the information so that it becomes accessible and actionable in your editor. Given that the Number 1 Challenge for developers today is sharing knowledge, CodeStream sits exactly where the intersection of documentation and collaboration lies. Collaboration solutions that are specifically designed for developers will become the foundation of useful on-demand documentation.
The future of documentation in On-Demand
The future of software development will include a higher percentage of remote co-workers and teams. We have seen that an all-remote approach requires flexibility, the right collaboration tools, transparency and visibility. It also requires a new approach to documentation if we are to make all-remote work as effective as sitting side by side in an office. Adopting an on-demand approach to documentation solves two problems we have been wrestling with for a long time. It relieves developers from investing time and effort trying to figure out what others might not understand, and it improves knowledge sharing not just among two developers but for the organization as a whole.
Oldest comments (1)
80/20 rule for documentation:
1 Put in a header comment for a class (or equivalent metaphor depending on your language) explaining WHY the class exists. What is its purpose in life?
2 Good naming of methods (functions, whatever).
3 Small methods (functions).
Perhaps CodeStream could offer enforcement of some of the above? (OK, hard to enforce "good"! :-) )