We’ve already unpacked why great documentation is crucial for the longevity of any serious software endeavor. From supercharging developer productivity to de-risking sudden team changes, software docs play a pivotal role in the lifecycle of a codebase.
And yet, there remains a stark gap between talk and action. In practice, a vast majority of the 100+ billion lines of code written each year go undocumented.
Which begs the question — if documenting code is so crucial for the health of a project, why do so many developers steer clear of it?
Let’s explore what themes lie behind this curious paradox.
BEHAVIORAL FACTORS
1. Writing docs is uninspiring and monotonous
The art of coding is a creative, engaging and exciting process. Documenting, on the other hand, is a far cry from the stimulating highs of coding. An activity that is uneventful, unglamorous, even dull.
Think about the 14-year-old who first fell in love with programming, drawn in by the joy of breathing life into their ideas. It wasn’t the prospect of methodically explaining their work that sparked their passion. It was the allure of creation, the challenge, and the excitement of problem-solving.
The shift from the animated world of coding to the tedium of writing docs is both off-putting and draining, leading to many developers avoiding the latter passionately.
2. Context switching gets exhausting
Juggling between the highly technical, problem-solving mode of coding and the explanatory, descriptive mode required for documenting that code is mentally taxing.
The cognitive load introduced by this constant back-and-forth makes documenting feel like a tiring and colorless chore. Programmers find such interruptions to their creative flow especially irritating, leading them to procrastinate on documentation.
An outlook of I’ll-document-it-later emerges, but in the fast-moving world of software development, later frequently translates to never.
3. Lack of immediate gratification
You write a piece of code, you execute it and voila, the result of your hard work is there for your team to see. Time to push out that feature and get your daily dose of dopamine.
In contrast, the benefits of documentation are seldom as quickly verifiable. Software docs only become helpful when someone down the line (possibly even you ) needs to refer back to the code and understand its logic.
Developers often treat documentation as an afterthought due to the lack of instant acknowledgement — something to be handled only after the real work of coding is complete.
4. Overconfidence in one’s abilities
Programmers routinely fall into a trap of self-assurance, believing their experience and expertise render software docs unnecessary. They overestimate their abilities to recall the finer details of their code after extended periods, and consequently resist any requirements to document their work.
Developers also often misjudge the time they need to write effective documentation. When they find out afterwards — much to their frustration — that commenting code demands much more time than they previously estimated, team morale diminishes. This further reinforces the general hesitation towards any documentation tasks in the future.
ORGANIZATIONAL FACTORS
5. Working with finite resources
Engineering teams are always under the gun to demonstrate tangible progress of their work. This is often measured by lines of code, number of commits or features pushed to production.
Given the choice between allocating developers to immediate coding needs or to documentation, most teams opt to deliver functional code on time.
Any activity not perceived as immediately essential — like documentation — is all but overlooked. Commenting becomes a quick box-checking exercise rather than a thoughtful process aimed at adding long-term value.
Even if docs are written, their quality suffers. Future needs of the codebase be damned!
6. Documentation doesn’t fetch bonuses
Tech company culture glorifies complex coding feats. There’s a higher marginal incentive in today’s competitive work environment for writing the next line of code versus explaining a piece of code that is already written.
This echoes in how companies evaluate developer performance, with the scales tipped heavily in favor of coding achievements.
The invisible is seldom incentivized.
This absence of recognition or rewards for well-maintained documentation means there is little external motivation for engineers to invest time doing it.
7. Difficulties in expressing short-term ROI
The return on investment (ROI) of good software documentation is not easily measurable in direct terms, especially in the short term.
Documentation may save a company time and money by ensuring the longevity of its proprietary codebase, but it does not directly generate revenue or immediately contribute to its top-line.
This difficulty in quantification can lead to a view that documentation does not offer a clear benefit to a company, influencing its priority on scrum boards.
8. Agile methodologies downplay documentation
Agile techniques focus on adaptability and swift delivery. This strong emphasis on rapid iterations causes long-term essentials — like documentation — to be routinely relegated to the sidelines.
As projects scale and become more complex, so too does the volume of documentation required to keep things comprehensible. Consequently, agile teams find it difficult to spare story points for what seems like an ever-expanding task of retroactively commenting code.
Faced with such challenges, it’s just simpler for developers to concentrate on the next sprint and leave the task of piecing together docs to someone else in the future.
TECHNICAL FACTORS
9. Documenting once is not enough
Codebases, like the Ship of Theseus, constantly metamorph through refactors, bug-fixes, optimizations and extensions. Even code that fulfills the same requirements may vary in implementation over time.
Keeping docs fresh and in-sync with code changes in such a dynamic project-scape is like hitting a moving target. Every tweak, every new line of code, every feature removed demands a corresponding update in the documentation.
This need for constant vigilance and revision is a logistical nightmare, discouraging developers from spending time to write docs.
10. Developers aren’t the best writers
Translating intricate pieces of code into clear, concise explanations that others can readily grasp is no small feat. And the skills needed to write effective documentation aren’t always congruous with technical proficiency.
Even the best software developers may stall when it comes to expressing themselves clearly in plain English. Since writing prose puts many developers out of their comfort zones, many choose to avoid documenting code and double-down on their technical output instead.
A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments. — Kevlin Henney
11. Automated tools don’t fit workflows
Programmers are creatures of habit. They cherish their established workflows. And they want tooling that seamlessly integrates into these processes.
Using assistive doc generation tools often involve steps that are disruptive to developer workflows — whether it’s opening up a new custom interface, executing a new set of terminal commands, or interacting with half-baked suggestions from a chatbot in the midst of focused coding sessions.
The idea of adding even one minor step to their long set processes results in a lingering reluctance to adopt these solutions in order to safeguard one’s rhythm and productivity.
CULTURAL FACTORS
12. Good intentions get lost in translation
Although English is the lingua franca of the software world, it isn’t everybody’s native language.
Expressing technical jargon and intricate concepts accurately in a language that doesn’t come naturally to you is a lengthy and demotivating exercise.
Even when developers do their level best to comment their code, language limitations can result in documentation that is riddled with errors in diction, vocabulary, or grammar; producing docs more puzzling than the code itself.
Combine this with feelings of inadequacy in the company of colleagues more fluent in English, and you have a scenario where non-native speakers are systematically discouraged from documenting their code.
13. CS curriculums don’t emphasize documentation
Dive into the curriculums of an average computer science or software engineering program, and you’ll find negligible content reinforcing the need for commenting code. Many skip mentioning it entirely.
This educational oversight sets a precedent early on in a programmer’s journey.
Even in industry, continuous learning courses for professionals frequently skip covering effective documentation skills. As a result, even seasoned developers repeatedly find themselves at sea when it comes to effectively documenting their work.
They have the technical prowess, no doubt. But they never learned to appreciate — much less create — helpful software documentation.
14. Impact of peers who don’t like documenting
Attitudes prevailing amongst industry colleagues impact developer workflows. In environments where peers undervalue documentation, the mindset becomes entrenched.
Groupthink is real.
And when senior devs and mentors in a community treat documentation as a waste of time (or worse still, broadcast sentiments like good code doesn’t need comments), those who learn from them are less likely to prioritize documenting their own work.
This perpetuates the diminished importance of documentation in successive generations of developers.
PSYCHOLOGICAL FACTORS
15. Satisfying a diverse audience is hard
The idea of documentation is to make a codebase accessible to a range of contributors with varying levels of experiences, skill-sets and psychologies. Even entirely non-technical stakeholders may need to refer to software docs for solving issues in their respective work-streams.
Producing inclusive documentation that caters to such a wide audience and satisfies all (or even most) stakeholders requires a heavy dose of patience, iteration and interpersonal skills.
Who’s got time for that?
16. Short supply of empathy in tech cultures
At its core, writing clear and comprehensive documentation is an act of empathy. It requires considering the needs of others who will interact with their code in the future.
When developers claim that their code doesn’t need explaining, they overlook the needs of those with lesser or different domain-specific experience. The nuances of a codebase — immediately obvious to the original author — may thus remain ambiguous to future handlers.
The altruistic mindset required to diligently keep one’s code commented clashes with the more individualistic narratives prevalent, even celebrated, in popular tech culture.
17. Job security through code obscurity
Developers sometimes find it beneficial to avoid documenting their code as a means to solidify their place within an organization.
By being the only ones who fully understand the intricacies of a codebase (or even a portion of it), they make themselves an indispensable resource to a team; someone who can’t be easily replaced in the face of layoffs or performance issues.
In highly competitive work environments with fragile job stability, developers may be forced to resort to such knowledge hoarding as a survival tactic.
18. Not everyone cares for the project
Many software professionals are in the field for the instantaneous rewards, and are not necessarily concerned with the long-term sustainability of their assigned projects. Factors like ease of maintenance, knowledge transfer and future scalability are hardly a priority for someone just looking to meet their next milestone and get paid.
This tendency is only reinforced by a deeper cultural issue in the software industry that respects individual accomplishments over collective success.
Developers who singularly focus on getting-the-job-done eschew documentation, promptly pushing off any concerns around transferability on future contributors to the project.
Phew, that’s quite the list!
It’s no wonder engineering managers have a hard time coaxing developers to document their work.
What’s abundantly clear is that the resistance to writing docs isn’t just about developers being lazy or neglectful — it is something deeply intertwined with the mental models, communal attitudes and broader cultural frameworks prevalent in the tech industry.
By acknowledging these practical hurdles to software documentation, we can start building opinionated solutions that align with the preferences and working styles of developers.
Perhaps then there is hope that all software will one day be consistently documented.
Our next article will be the story of one of our engineers – detailing his journey from burnout to brilliance, and how he re-ignited his passion for coding. In the meantime, check out Komment, a product that seamlessly integrates into existing developer workflows and delivers on-time, in-sync docs to coders and their teams.