Our Blog

marketing and developer relations

Best of 2018: Why Your Developers Should Not Write Your Product Documentation

January 22, 2019 - Content Marketing, Marketing - ,
By: Chris Riley

For organizations that sell directly to developers, or have public-facing APIs, their product documentation is a unique opportunity to educate, drive adoption, and market. Yes, I said market. Many organizations don’t realize how powerful documentation can be as a marketing tool. So if you are selling a product to developers or developer relations, and you need to get their attention, consider how documentation can help you, and why your engineering team should not own it.

Documentation use cases

Before any of your engineers scoff at this post, or before you get nervous about needing to be a developer yourself, pause for a minute. Your engineering team will always have their own set of documentation that is used to build the product. It’s not public (this will be a key point later), and it has a depth that only a person with intimate knowledge of the code base will fully know. I am not suggesting that should go away, or that marketing should control it.

What I am proposing is a new set of docs. (That sounds scary as well.) But in reality, it’s happening already, with nearly the same effort, but less overall value. Organizations just don’t realize it. They do not think about the refactoring time required to convert internal docs to public. It’s not a trivial effort, and engineering’s time does not improve the product.

How documentation benefits marketing and developer relations

Now that we’re past the fear, let’s talk about the benefits:

  1. 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. And only how-to, code-level content can fulfill that. 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. Because documentation is very heavy with this type of content, it will be indexed high, and will indirectly be a draw of traffic to your documentation pages from a very targeted audience.
  2. Call to Action (CTA): The first point above brings us to another benefit. If engineers create the documentation, they often do not think about the developer’s journey, and they certainly do not think about how you can take a net new user who is visiting documentation pages to a trial user or paid customer. There is a very fine line to walk here, but well-architected documentation will have a clear path to landing pages and product registration.
  3. Happier Users: Also important—Your users will thank you. Even when a developer finds a product they love, they will almost always say, “the docs suck.” Documentation can be poor for a lot of reasons, but the top ones are:  

a. Created haphazardly as an afterthought: Creating public-facing documentation is not a priority in the face of high-pressure development environments where features need to get out the door. This will reflect in quality (typos, mistakes, gaps, etc.) Public docs can greatly benefit from being deliberate.

b. Missing information: Because creating docs can be haphazard, there are almost always omissions. But the omissions are not always because of sloppiness. Portions of the docs may be deemed as low-priority because of the assumption that you should be able to interpolate how to use the product without being told.

c. The assumption that you are a member of the engineering team for the product: This gets us to the assumption rooted in internal docs, and that is: The developer consuming the docs already knows a ton about the product. So some things should be common sense, right? Often, they are not. And docs do not tend to follow the developer’s journey. If you are net new to the product, or even net new to the tech segment, you should not be locked out.

There is an added benefit when engineering is not creating the docs, because you have opportunities to create conceptual how-to articles, to articulate deeply technical use cases, and to showcase case studies, which makes for lots of rich SEO content and technical product marketing material.

Then who writes it?

I said you don’t need to be a developer to make the content digestible. So who writes it, then? Documentation still needs to be written by coders who use the product. It needs to be detailed, and tested in the real world. But your target practitioner is the one who should be writing it—external users of the solution, leveraging a proven methodology for documentation structure and creation. Finding and managing three or more practitioners to do this can be very tricky, and this is where our documentation creation services have been popular.

In the wild

Companies like Wercker (now Oracle Wercker), HashiCorp and Docker have proven that good documentation makes a meaningful impact on the perceived quality of their solution, its adoption, and that high-quality documentation will serve as great market education and a web traffic driver.

The takeaway

Although documentation is seen as just a technical tool, engineering rarely proves to produce public documentation that meets the standards of the user base. But docs have also proven inadvertently to be a great marketing and developer relations tool. That is why it’s worth strongly considering whether marketing and developer relations teams should take over the creation of public documentation.


Chris Riley (@HoardingInfo) is a technologist who has spent 12 years helping organizations transition from traditional development practices to a modern set of culture, processes and tooling. In addition to being a research analyst, he is an O’Reilly author, regular speaker, and subject matter expert in the areas of DevOps strategy and culture. Chris believes the biggest challenges faced in the tech market are not tools, but rather people and planning.

    Would you like to share your thoughts?

    Leave a Reply

    This site uses Akismet to reduce spam. Learn how your comment data is processed.

    Subscribe to the Fixate IO Blog Highlights, Amplify

    Keep up with the latest Fixate IO blog posts about influencer content marketing for B2B and increasing share of voice.  Sign up here: