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.