Why wouldn't a company choose to have the developers who write the code also write the documentation for that code? Is it not the case that the ones who write the code are the ones best equipped to explain it to others?
The answer is an unequivocal and absolute no. The developers who spend countless hours writing the code, should absolutely not be the ones tasked with producing the final documentation for it. This will create a definitively poorer experience for the users who need to work with the product/tool/SDK they have built.
To understand why that is the case we need to understand two things:
- The cognitive bias known as the curse of expertise
- The distinct profession of technical writing
These two aspects combined make a compelling case to keep the core developers of a product as initial producers of the docs, at the most, but never the final authors, and certainly never the arbiters of what is a good documentation experience for others.
In 1990 a researcher at Stanford University asked random participants in a study to assume the role of either "tapper" or "listener". The tapper was tasked with tapping out on the table the popular Happy Birthday song, while the listener was asked to identify the song from the taps.
How often do you think people guessed the song correctly?
2.5% of the time.
At what rate do you think the tappers assumed the listeners would be able to get the song before the experiment began?
50% of the time.
Think about that for a moment. How could there possibly have been such a wide disparity between the estimation of success and the actual results?
Enter stage left the cognitive bias of the curse of knowledge or the curse of expertise. Once someone knows something, they are cursed (hence, the name of the bias) with that knowledge and are challenged from being able to imagine the difficulty others have in assimilating that information.
What does this have to do with writing good documentation? Well, everything!
Those who are tasked with writing the codebase are undoubtedly the single greatest experts in that codebase. They know every class and every method. They understand why they made an odd choice in that one bit, or why they chose to use a certain naming convention in another bit. This knowledge came through the hard and exhausting process of iterating on the code over and over again until it was ready to be shipped. They earned that knowledge.
Yet, now that they have gone through that process, their ability to empathize with others who are new to it is challenged. Not all the time, there are those who can overcome that cognitive bias, but certainly most of the time.
This challenged perspective leads to incomplete docs because they assume a lot of knowledge on behalf of the reader.
If you have ever used docs to build with an SDK or a library and experienced the frustration of needing to spend hours to figure out the one part that wasn't mentioned in the step-by-step guide, you have most likely experienced the result of this bias in action.
Docs must be written by someone other than the person who wrote the code.
The person who needs to learn the codebase in order to write the docs can model that learning in the documentation journey they craft. The person who comes to the codebase not from the hard earned place of the code author, but from the place of "user #0" will make sure all the bases are covered, and a step is not missing in any guide they produce.
This is one half of why the developers should not be tasked with creating the final documentation experience. The second reason is because technical writing is not a subsidiary field of software development, and its discipline and practice cannot be inferred because someone happens to also be an excellent software developer.
Technical writing is its own discipline and expertise.
Documentation is a learning journey for users, both docs for fellow developers and non-technical folks alike. This journey should not be crafted haphazardly and with no grounding in any recommendations from the field or learnings from peers in the space.
An excellent software developer can be an excellent technical writer, and vice versa. However, that excellence does not happen just because they are a great software developer and by virtue of their skill in one area. As a person learned to write code, a person can learn to write prose.
All too often, engineering teams are given free reign to own the end-user experience of the products they code, whether a framework, an SDK, an extension, a library or anything else. Good leadership helps eager engineers know their limits, and provides avenues to train developers excited to contribute to the user learning journey.
This is not to say that developers have no role in the docs. That is also absolutely not true.
The developers should be consulted to ensure accuracy, any challenges the writers experience in using the product while producing the docs can be fed back to product and/or engineering, and devs should be encouraged to produce quality code comments that can be the kernel seed for documentation. There are even opportunities for developers to write first iterations of docs and then hand them over to those in the discipline of technical writing for refinement and review.
What about small teams without the resources for this clean division of labor?
In that case, of course devs must write the docs as there is no one else to do so. While doing so, it is important to be aware of the cognitive bias of the curse of knowledge, and to spend some time studying from the technical writing industry. There is a wealth of knowledge freely available online for people entering into technical writing.
It's also imperative to mention the benefit of cultivating a robust open source culture. Whether your product is open source or not, your docs and the docs platform certainly can be!
Similar challenges toward quality documentation exist when soliciting community contributions as when engineers are writing the docs. However, for the most part, you are working with an audience of people who are your users, and thus are encountering the product not from a perspective tinted with the curse of expertise. They are your users #0, #1, #2, and onward.
Your docs are for many of your users the first entry point into your product. They are meant to be a journey that takes a user from rookie to expert and all the steps in between. It can be tempting to leave this fundamentally important resource in the hands of your experts, the developers who wrote the product, but doing so, unless you have no other choice, is often a mistake.
Whether through community contributions, working towards a budget that enables hiring people in the discipline of technical writing, providing the skills for developers who want to write to be able to do so, or some combination of all of the above, do not neglect your docs and give them the professionalism and respect they need to help your users succeed.
Top comments (13)
"cognitive bias of the curse of knowledge or the curse of expertise"
This very true. When I sit down to write documentation for any codebase I work on, I tend to assume that the reader would understand how some things work out of the blue. Which leads to poorly written and incomplete docs.
I agree cognitive bias is huge, which we should do as much as possible to mitigate. Having at least someone of the target audience (besides the developer) check the docs is a must for me. If sharing knowledge is a team/company priority (which I wish it would be at more places), having another person write the docs would be an excellent way to do this.
I'm a big fan of lightly sketching docs before coding because it helps guide my development, and communicate to my team early on. To me, it's the same philosophy as Test Driven Development - you should do it at some point, so instead of it being a chore, treat it as a canvas to guide your coding.
I feel a bigger problem than this, is that I've seen too many teams have little to no docs at all. You then have new members struggle to onboard, old members struggle to maintain, and everyone has to dig their head in the codebase for a long time to make sense of it all. It doesn't scale and is just wasted time.
My philosophy is that communication is key to building great software. And great communication to me happens throughout the dev cycle, is shareable, simple, and can reach a wide audience.
Agree with a lot of this. The only thing I'd add is that there is a difference between internal facing docs, which was not the focus of my post here, and external facing docs for developer users of the product, which was the focus of the blog post.
As I mentioned to another person who commented earlier, the same expectations of creating a documentation journey don't apply, in my opinion, on internal facing docs and certainly not on docs used for docs driven development. Although, there definitely should be some standardization and expectation of quality on them absolutely.
What's your take on the opposite approach? Writing the docs first, as a design document, and the code later, making tweaks to the docs when needed?
I'm a big fan of that approach. Documentation driven development can help the dev team map out exactly the specs they are building against, clarify edge cases, etc., etc. I'd just say that those docs produced in the early stages I'd classify them as internal docs, which don't have the same expectations on them as external documentation, in my opinion.
Interesting take.
Weird, the first thing I would assume is having a developer writing text documents is cost inefficient. Anyway, couldn't it be generated using AI nowadays? 🤓
AI can definitely be a big assist nowadays! It's not sufficient yet still by itself, but maybe that'll change soon? 😅
I wonder how much this can be countered by having external reviews for documentation, and treating it as a key part of the release process.
Who will be doing the reviews for the docs in the release process?
If the reviews mandate technical writers and/or folks trained/experienced in the discipline to be reviewers w/the ability to hold off a merge if it doesn't meet standards, then I think that would be a good approach. I worked somewhere where that was the case, and I think it went pretty well.
Great post
Hm, good priorities, except for one. Write the source/design documentation before the code. The code will be better and the product too. The coder van be anyone skilled enough. The documenter should be able to write and understand the domain. First document, then code!
Both developers and technical writers are key to quality documentation AND usable software, APIs, and so on.
When technical writers work hand in hand with developers before coding begins (or early in the development process) omissions in functionality, poorly named or too similarly named functions, incorrectly typed variables, and so on can be identified and corrected before code goes into production. Additionally, many technical writers are also programmers and can test that examples from their documentation work as expected once the code is live.