Documentation Belongs in Engineering

(This is all written with companies that build high-tech products used by engineers in mind.)

Many product companies start out with a very heavy focus on their engineering teams. It’s logical: You have to build a product to sell first and many roles make no sense until you have something to sell.

This also means that the engineering team will take on many roles: support for the first users, building the company website, building some internal tooling where absolutely necessary, writing and hosting the documentation.

At some point, many companies move the hosting and writing of documentation out of engineering and into a separate part of the company. It could be marketing, it could be customer success.

I think that is a grave mistake.

Why are companies moving the team out of engineering? In the worst case, it’s “because everyone does it”. In a more common scenario, documentation quality is lacking and someone feels like the engineering team is simply not able to write and maintain good documentation.

This is where I strongly disagree. I think many engineers are very good at writing documentation.

Then why does the quality of documentation written by engineers start to go down over time so often?

It is because everything around them starts to become more structured compared to the early days, but no one makes adequate time for them to write and maintain documentation.

Suddenly someone writes a roadmap. Suddenly there are project managers. Suddenly customers have been promised a feature. Now the most important thing is to get that feature out and time for documentation is an easy thing to cut or remove entirely - if it was even planned for in the first place. (This is also why long-term roadmaps and promises to customers are a terrible idea.)

Instead of fixing that problem (making sure features are always released in a finished state), someone creates a new problem by creating an independent documentation team somewhere else in the company.

Please don’t get me wrong: Professional technical writers are an absolutely fantastic thing to have in your company, and they have incredible skills that likely no one else has. However, I believe that they cannot be successful in a high-tech product company if they are not deeply embedded in the engineering team. Their skills should be used to help guide engineers write good documentation. They should own the overall structure of the documentation and make sure it makes sense and is easy to navigate. They should take and constantly improve what engineers wrote. I know that many engineers would absolutely love to work directly with technical writers and learn from them.

What happens instead is that there are now endless meetings of discussing notes of new features so the poor documentation team even knows what to document. There is often no way to even start documenting anything before the beta phase - way too late. The frustrating feeling of “I could have just written this myself in the same time” feeling starts to creep up. Even worse, releases may now be delayed until the documentation is ready and if there are questions, engineers are already working on new features and have to context switch. Messy and frustrating for everyone involved.

Small changes? Have to go through a different team now that’s on their own roadmap because the new docs system is not accessible for everyone. Maybe it was just in git before but is now a SaaS with seat-based licensing and someone was cheap. Frustrating. This used to be easy.

Because it’s now the docs team’s job, engineers are probably still not getting enough time to take care of documentation, leading to friction with the documentation team that rightfully feels like they get no help from the engineers. In the most toxic organizations, the blame for bad documentation is still thrown at the engineering team.

Once documentation is no longer done in the engineering organization, key decision makers for it are likely to be less deeply engaged with the end-users of the product. (Again, this is with high-tech product companies in mind) You could suddenly see discussions about call to actions or even sales forms in the documentation, not understanding how or why people use documentation. The technical writers are likely the only ones that would hopefully be advocating to avoid that.

Before you know it, documentation becomes another channel instead of one of the most powerful tools you have for generating a ton of successful customers without spending enormous amounts of time and money on professional services, support and customer success teams. Instead, it becomes slow, out of touch and cluttered with distractions.

My advice is to use all your power to keep documentation in engineering. Hire great technical writers, make them successful by working with engineers in a great relationship and fix the underlying problems in release planning and promises to customers that lead to a poor documentation experience in the first place.

The people who write the feature get the time and resources to explain it. Technical writers make and keep it world-class.