Developer Relations Why Your Developers Should Not Write Your Product Documentation
August 7, 2022
If your organization sells directly to developers (or has a public-facing API), your product documentation is actually a unique opportunity to market and drive adoption. In fact, many organizations don’t realize just how powerful it can be as a marketing tool. In this post, we’ll explain how to use your documentation to attract the attention of developers and developer relations advocates. Then, more importantly, we’ll explain why your own developers should not write it.
Documentation Use Cases
Before we get started, let’s clarify exactly what we mean here. We are not talking about the documentation that your engineering team uses to build your product. Your team should always have their own set of documentation, and we’re not telling you to make that documentation public. In fact, only someone with intimate knowledge of your codebase will be able to appreciate the depth of that material. We are not suggesting that you get rid of it—or that marketing should take control of it.
What we are proposing is a new set of product documentation. That might sound scary, but in reality, it’s already happening…with nearly the same amount of effort, but less overall value. Organizations just don’t realize it. They’re not thinking about the time required to translate internal documentation into user resources, answered questions, and practitioner marketing. It’s a critical and time-consuming effort. If you don’t make the effort, or if it doesn’t come out well, you risk losing clients. As we’ll explain, your engineers should not be the ones to write it—for several reasons.
How Product Documentation Benefits Marketing and Developer Relations
Now that we’re on the same page, let’s talk about the benefits:
- Search Engine Optimization (SEO): Deeply technical content performs very well with search engines. The reason? Because it is keyword-rich, and it answers very specific questions. When techies perform searches in the heat of development, what they search for is very specific. Only how-to, code-level content can fulfill their needs. It’s in those moments that you want to catch them, because they are likely overcome with a challenge or question. You might be the answer. Since product documentation has exactly this type of content, it will be indexed highly, and it will indirectly draw traffic to your documentation pages from a very specific audience.
- Call to Action (CTA): The point above brings us to another benefit. If your own engineers create the documentation, they usually won’t be thinking about the developer’s journey. They’re almost certainly not going to be thinking about CTAs geared to converting net new users to trial users and paid customers. Furthermore, there’s a very fine line between being pushy and providing a clear path to landing pages and product registration. This kind of writing simply isn’t part of their job description.
- Happier Users: Importantly, your users will thank you. Even when developers find a product they love, they will almost always say, “the docs suck.” (More on that below.) So, create the docs with them in mind to boost your developer relations.
Why Your Current Product Documentation (Probably) Needs Help
Documentation can be poor for a lot of reasons, but the top ones are:
- Your developers created it haphazardly as an afterthought. For people who work in high-pressure development environments where features need to get out the door quickly, creating public-facing documentation is simply not a priority. Consequently, the quality will suffer, and your docs will be rife with typos, mistakes, gaps, and other problems. Product documentation needs to be well-planned and deliberate.
- It’s missing information. Since developers who create documentation normally do so haphazardly and in a hurry, they almost always leave things out. But the omissions are not always because of sloppiness. Your developers may deem some portions low-priority. They may also assume that you should be able to interpolate how to use the product without being told.
- It assumes that you are a member of the product’s engineering team. If the people who write your internal docs also write your product documentation, they’ll likely write from the same perspective. Like your internal docs, then, your product documentation will assume that the reader already knows a ton about the product. That means some things should be common sense, right? Often, they are not. And these docs do not tend to follow the developer’s journey. This kind of documentation can lock people out—especially those who are new to the product or the tech segment.
Then Who Writes It?
The best people to write your product documentation are influential practitioners from outside of your organization. Even though you don’t need to be a developer to make the content digestible, your product documentation still needs to be written by coders who use the product. It needs to be detailed, precise, and tested in the real world. That’s why your target user is the one who should be writing it. You need practitioners who can walk their fellow users through the intricacies of learning to use your product from the beginning of the journey.
Those practitioners need to be good writers—or to work with a team that can help them be good writers. Likewise, they need to be able to leverage a proven methodology for creating product documentation. Finding the right authors—not to mention the right formula—on your own can be tricky to say the least. That’s where Fixate can help.
Additional benefits of leveraging practitioner content include:
- New Opportunities: Having outsiders write your docs creates new opportunities to market and educate others about your product. For example, you can have them design conceptual how-to articles, articulate deeply technical use cases, and showcase case studies. That makes for lots of rich SEO content and technical product marketing material.
- Increased Share of Voice, Share of Conversation, and Credibility: As we’ve explained in another post, an outside perspective will help you build credibility, extend your reach, strengthen your developer relations, and increase your share of conversation, among other things.
In the Wild
Companies like HashiCorp and Docker have proven that good documentation makes a meaningful impact. It affects the perceived quality of the solution as well as its adoption. Therefore, high-quality documentation is an excellent way to educate the market and drive web traffic.
It seems logical to have your internal engineers draft your docs. But product documentation is more than just a technical resource. If done well, docs have proven to be an excellent marketing and developer relations tool.
To get the full potential from your docs, leverage unbiased and objective input from external DevOps practitioners. They are the ones who can fully anticipate the needs of your consumers, because they represent your actual audience. DevOps practitioners outside of your organization can audit and test your documentation through a lens of developer experience. They can measure your docs against practical expectations, and compare their usability with other docs that have proven to be valuable.
You’ve invested greatly in product development and testing. Maximize that investment by giving your prospects and buyers documentation that ensures the best experience possible.
This post was originally published in May 2017 and updated in November 2022.