I’ve wanted to write this post for a while now, as with every day that passes, I believe its message more and more: truly, every developer should care about documentation. And I really do mean every developer.
Personally, documentation is something that I care about and is closely related to my passion for the sharing of knowledge, self-education, and the belief that coding should be accessible to all.
However, I realize that not everyone shares these passions, so I’ve set out to compile a list of practical reasons why developers should care about documentation (spoiler: documenting your code is often as much a benefit to yourself as it is to others!).
Table of Contents
- Clarification
- Part A: It’s For Your Own Good
- Part B: For the Good of the Team, Users, and Everyone
- Final Thoughts:
Clarification
Before getting started, I should clarify for whom and how this post might apply. Starting with the term documentation:
The term documentation can refer to a lot of different things; README files, Wikis (e.g. Confluence), inline code comments, or even documents that are auto-generated directly from the source code!
Within the scope of this post, I’ll be talking about documentation in general, although the focus will be somewhat on more verbose forms of documentation, such as README files.
And for “whom” do the points in this post apply to? Well, I stand by my article title – yes, every developer should care about docs – but, at the same time, I acknowledge that some specific points (such as using doc writing as motivation) might apply less to those in highly regulated industries or working in a role that is already driven by tight requirements and things like BDD.
Part A: It’s For Your Own Good
Since I often see that it is difficult to get some developers to care about documentation, since they claim they don’t see any personal benefit from spending time on it – I’m going to start by challenging that fallacy. Even if you are a team of one, only working on your own solo project that only you use, there are still very important reasons to care about documentation.
Documenting Code Uncovers Bugs, Vulnerabilities, and Issues
This goes hand-in-hand with my point about “dogfooding” (more on this later), but often a underappreciated way to find bugs, security concerns, and issues that need to be raised is to write documentation, and / or working on keeping it up-to-date.
I’m not going to go deep into discussing things like requirements and specification languages, but they are an obvious tangent to this point, and can have a similar effect.
The reason why I say that writing docs can help a developer uncover bugs and issues is because the act of writing them often challenges the assumptions they might have about how their code works, and forces them to see their system in a new context.
When you are writing and viewing code, unless your code base is extremely tiny (or your monitor is extremely large), you are never seeing the entire thing at one time. Your brain conveniently fills in the gaps – you know that when you call method X, it is going to do thing Y and Z.
The same thing generally goes for thinking about the user experience (or developer experience) – the model of what the experience looks like is too large to “see” at a single moment, so you either consider a tiny part (“What does it look like for a user to request an authentication token from us?”), or for the macro level, you brain goes back to its old tricks of filling in the gaps and abstracting into broader levels.
Reading the above, you might see how this could lead to issues. Assumptions are dangerous in software development, and although tests might catch bugs, or even visual regressions, they don’t generally check experience or usability, they check that something works and meets preset expectations. An application might compile and run without crashing, but fail to be functional in a practical sense.
Writing documentation encourages you to slow down, see your code in a new context, and challenges assumptions you have about how your own codebase works.
Writing While “Dogfooding”
One of my favorite “side-effects” of writing documentation is that it often forces a developer to “dogfood” their own product (or area of the product that they are working on).
For those unfamiliar, the term “Dogfooding” usually refers to the practice of using your own product or service.
There is often a disconnect that happens with software development, where people end up working on features that they never use themselves. In my opinion, this is also a large contributing factor to how we end up with scenarios where a feature is released or updated in a way that makes the user experience worse for many users, and they are left wondering: “Why did no one realize how unusable this is?”
Writing documentation usually forces the person writing it to, at the very least, run through the basic steps of using the thing they are writing about. This, in turn, has a couple huge benefits:
- The author might discover new features that can be added in the future. This might come about in several different forms of realizations:
- “Wait, our product doesn’t do ____? We should add that!”
- “Huh, what I’m documenting sounds useful, but I have a feeling it could be better if ___”
- “This can’t be all there is to ____!”
- The author might discover shortcomings in existing features
- “Wow, this should not take this many steps to do! Our users put up with this?”
- “This can’t be right…”
- “Wait, how does this work again?”
- The author might realize ways in which their mental model of the application has diverged from what actually ends up getting delivered to the end-user
- “I could have sworn it worked this way!”
Improve Productivity
Comprehensive documentation can have a massive impact on developer productivity, when you consider that it can have all the following effects:
- Reduce employee onboarding time
- “Getting started” docs, even if only internally used, can greatly cut down on time to get a new dev setup
- Reduce redundant questions / issues
- I love people asking questions – it is a necessary part of growth. However, if you have multiple people all asking the same questions over and over again, that is a good sign that the knowledge they are seeking is important enough to belong in shared documentation
- Reduces delays / “knowledge latency”
- No one wants a project held up because everyone is waiting on one person with secret knowledge to reply to a long email chain
- Docs don’t take vacations, they aren’t going to burn out from everyone pestering them, etc.
Documentation Driven Development
Starting with Docs is Motivating
This point is especially true if you are a “indie hacker”, solo coder, entrepreneur, etc. – writing documentation can be extremely motivating if you approach it with the right perspective(s).
In explaining this point, I’ll start off with what is probably the wrong approach if your goal is self-motivation: don’t leave writing documentation as the last thing to do, as a final step when all the code has already been written.
Instead, to use documentation as motivation I would suggest writing and updating docs actively as you work, or even writing ahead – describing features that you aspire to one day implement (making sure to either keep these out of public-facing docs, or clearly marking them as “roadmap” items).
This might not work for everyone, but I often find that if I have already written down the basics of a feature that I’m personally excited about, having that documentation in front of me is highly motivating; even if it is just a single bullet point, having it written down helps me visualize the end-goal and focus on my desire to make it become reality.
Starting with Docs Is a Legitimate Pattern
I’m far from the first person to think that starting with the docs is an approach worth exploring. Those who have been in software for some time might already be familiar with a lot of related topics:
Part B: For the Good of the Team, Users, and Everyone
Developer Experience and Relations
Developer Experience / DX
If the product that you are working is something that is developer focused (e.g. an API, SDK, Framework, PaaS, etc.), then you might already be aware of how critical documentation is in eliciting a positive developer experience (DX).
However, something that often gets overlooked is that, in the same way that having a lot of tests is not necessarily the same as having high test coverage, having a lot of docs is not necessarily the same as having documentation that properly covers the developer experience of your product.
To be fair, there is a very fine balance between too much documentation (which can overwhelm the user / dev), and too little or sparse documentation. But at the end of the day, there is a truth which is hard to ignore – you can build a dev product that beats every competitor out of the water with features, stability, and performance – but without docs, without a way for developers to know how to use your product – you can’t expect people to jump on board.
Developer Relations (DevRel), Advocacy, Evangelism
The role of a developer advocate, if you want to boil it down into the core purpose, usually comes down to “helping developers (use your product)”. In the context of this definition, I don’t think anyone will argue with me that docs are a big part of helping developers, but sometimes there are more subtle influences that documentation has on developer relations aka DevRel):
- Evangelism and driving product growth
- Usually, under the umbrella of DevRel, one of the objectives is spreading word about the product to developers and helping to drive growth. (“Hey, it’s a business after all!”)
- People often focus on blog posts, viral tweets, and landing pages as the content that drives further adoption, while neglecting to talk about docs
- Good docs can help drive growth, especially if attention is paid to proper SEO (Search-Engine Optimization) and organization
- There are a number of products that I have found, and started using, only because I ended up on their documentation while researching something related.
- Conversely, there are also some products that I have avoided entirely, or hesitated trying, due to what I perceived as sub-par documentation
- Some products are renowned for the quality of their docs, and that itself can become a driving force behind “word-of-mouth” growth
- For open source: driving contributions and community interest
- If your product is open-source, and you are looking to get the community more involved and grow the number of contributors, documentation is great way to do so
- Documentation is often the entry-point for a developer, before pretty much anything else, so it becomes an easy place for developers to contribute back to the project by addressing shortcomings in the documentation as they on-board themselves
- Example: Developer opens a Pull-Request (PR) to add a section to the “Getting Started” section, with added instructions for Windows (current docs only have instructions for Mac or *Nix)
📄 Further reading:
Empathy
The best documentation is inclusive and meant for as many people as possible. Writing documentation with this outcome as the goal is a great way to challenge yourself to approach your codebase with greater empathy for other developers.
As a Form of Backup
Just like code and data, knowledge needs protecting and backing up too! A bunch of code without the information on how to run or update it does not hold much value in practice.
If you mention the words “backup”, “recovery”, or “redundancy” in a room full of software industry professionals, you are likely to get swarmed by multiple people who are all too enthusiastic to explain how their company’s systems are built to handle any sort of catastrophe or incident.
You’ll hear things like how they use multiple redundant backups, perhaps even replicating onto physical long-term storage, like tapes. They might backup every version-controlled repository daily, refusing to rely entirely on a third-party host like Github or Perforce, in case of a failure. They might boast about how fast they can rollback the data itself – reverting a DROP TABLE or rm -rf type incident with lightning speed.
You might also get an ear-full about how easy deployment and scaling are for them. Perhaps they have reached less than a minute of downtime per year (aka Six Nines, 99.9999% uptime).
However… try asking this same group of individuals how knowledge is backed up within their organization. Often, the answer is either “it isn’t”, or the efforts to organize, safeguard, and streamline documentation is miniscule in comparison to the systems it belongs to.
Why Does Knowledge Need Backing Up?
One way to think about this, which is unfortunately morbid, is “what would happen if ____ employee suddenly passed away”.
Or, if it makes you feel better, they were suddenly “made redundant” after they spilled coffee all over the server racks.
In many companies, information tends to get siloed – within a team, or even limited to a single person. You might ask someone “How do I change X in system Y” and get a response like “Oh! Morgan, the architect of system Y is the only one that can answer that.”. Or maybe you’ve been a participant on a message chain that goes something like: “I’m not sure about that… I’ll have to CC ___ in on this…”, until it turns out you need Morgan again.
Notice how these examples are also instances in which developer productivity is reduced, because we are now waiting on knowledge to be available (something I touched on earlier)?
Going back to our morbid question: what if we suddenly lose Morgan? Did they ever document how system Y worked, in a way that others can understand? If not, we might still survive – but it might take quadruple the resources – in time and money – to decipher their code and make sense of everything. Even if we can hire someone of exactly the same skill level, they aren’t going to be able to hit the ground running without having that system properly documented and the knowledge accessible.
🚍 The software industry actually has a term for the idea of how many people it would take suddenly dying (e.g. getting hit by a bus) before it brings down a project – the “Bus Factor”
Also, nothing against anyone named Morgan!
Final Thoughts:
Refuting Common Arguments
There seems to be a certain subset of developers that, the second someone brings up the importance of documentation, will (loudly) interject with objections and various claims of why they don’t need to write docs.
This is already a very long post, so I don’t want to spend too much time digging into these (maybe in a future post?). But I’ll very quickly give a response in list format
- “My code is self-documenting!” (or self-explanatory, or something like that)
- Nice try, but no. Even if you are using a strongly-typed language, your code can answer the question of how, but not why (that is what comments are great for). Well-name variables and readable code do great things, but they need to be part of a larger picture.
- ALSO:
readability !== maintainability
- “It’s just me! I know my own code!”
- If I we had time travel, there are a non-trivial number of developers that would all have bruises from when their future self went back in time to punch their past self for saying this. Yes, you know your own code now, but will you really feel the exact same way in a year? 5 years? 10?
- “Too many comments in code are a form of code-smell”
- People love to throw this argument around. They will use examples where a code comment will basically be identical to the code – but this is a contrived example, and not how comments should be written in the first place
- Again, comments should be mostly about the why, not the how. Docs such as READMEs can be all of the above (+ what, when, etc.)
- See responses in this discussion
- “We are already using auto-generated docs from [methods, JSDoc, etc.]”
- Auto-generated docs serve a purpose, and are good for things like describing API endpoints, but they often don’t add that much value on-top of the code they are generated from.
- “Docs get easily outdated. Code does not.”
- This is actually a reasonable point. See below
Preventing Out-of-Date Docs
The one argument against spending much time on documentation that I feel actually has some merit is the tendency for docs to get out of date (or out-of-sync) with the code they belong to. Critics will claim that bad docs are worse than no docs at all, which I don’t agree 100% with, but as someone who has been burned by bad documentation, can attest to the frustration that is felt when you waste time and effort because no one bothered to update materials.
This is a complex problem, worthy of its own in-depth discussion, so I’ll just provide what I find as the best counter-measure; the closer your docs live to the source-code the more likely they are to stay up to date.
This is where systems like Confluence, Notion, or shared Google Docs can potentially cause issues. In my honest opinion, those should be used for knowledge base (e.g. wiki) stuff, and documentation is better suited to things like Markdown files that live near the actual code (aka colocation).
Another important aspect is how easy is it, from a procedural standpoint, for new people to edit the docs? Can any new employee or contributor submit an update? Or does it require some lengthy approval and merge process, that is likely to discourage frequent edits?
I’m Not Perfect
Finally, I’m not asking that you follow every tip I’ve laid out here, or buy into the points I’m making without any objections. I’m not perfect, and some of the realizations I’m sharing here I have only because of painful learning experiences.
I’m only asking for a little more mindfulness around documentation, for everyone’s benefit.
Further Reading
- Holman: “The Most Important Code Isn’t Code”
- Cinger: “Fixing your Documentation Problem“
- Preston-Werner: “Readme Driven Development”
- Knuth: “Literate Programming”
Also, it would be remiss of me not to mention my extensive personal documentation project – docs.joshuatz.com
