Our Blog

API documentation

Your API Documentation Content Marketing Strategy

August 2, 2018 - Content Marketing, Practitioner Marketing - ,
By: Chris Riley

What could be more boring than API documentation? At least, that is how most of us view documentation—but not developers. API docs are one of the fastest ways to learn about a product and what it does. And API docs are one of the best opportunities to gain credibility, drive inbound organic traffic, and engage with your target users. That’s why you should have an API documentation content marketing strategy.

Often, your first impression to the developer audience is your documentation. The reason for this is that developers hunt it out. They don’t want to spend time reading marketing fluff, or consuming whitepapers (and for sure they will never read your press releases). They want to know the technical details of how your API works, and once they have decided to try it out, find some use cases.

We’ve already made a case for why marketing should own developer documentation, but in this post, we will talk more about how to make it work. The most difficult part of integrating documentation into your marketing strategy is the handoff between the developer-created internal docs and you. So let’s start there.

The handoff

Usually when marketing engages with engineering, there is a lot of frustration on both sides of the camp. Your engineering team most likely does not have a dev assigned to your projects. So any time they support you, they are taking away from what they want to do most—build features. But at the same time, your engineering team most likely does not want to be involved in refactoring the internal API docs to be customer-friendly public documentation. So a one-time project to make the handoff to marketing in an automated way usually is a win for all.

There are several ways to do this, especially now that a lot of developer teams have turned to tools like Jekyll, Hugo, and Middleman to automatically generate a static HTML version of their docs. The ask of your engineering team is to have regular general versions of docs in two locations during the release automation process. The first version is probably for them, and the second goes to a host of your choosing, probably your portal. These are easy to add. The hard part is the changes and architecture. Ideally you agree on an architecture, and do a one-time project to modify the hierarchy of the docs to better fit the developer journey.

If the marketing team embraces a source-control system for their entire developer portal (or at the very least, the docs portion), then changes will be caught, and someone on the team can easily be taught how to merge changes, and make edits of their own.

It will also benefit everyone to use a commonly accepted file format such as Markdown. (It’s likely this format will already be required by the tool which will generate the site.) Once that is done, the primary contributions from your team when the docs are deployed will be additional elements to make it more developer-friendly, some additional content to build in developer empathy and SEO power, and edits for SEO.

Once you have them

Once you have the docs, and the automation is built so that every time there is an update your engineering team won’t curse at you, the following are the areas where you need to put your touch.

  • Copyedit: As a marketer, you are not going to touch the language of the existing documentation. But you do need to make sure it reads well. Very often, the descriptions that come with API calls and examples do not read clearly and have typos. So every release needs a copyediting pass.
  • Host docs with your dev portal: You are not going to get much benefit from having control of developer docs if they are not both hosted with and boosting the traffic of your developer portal.
  • Think about portal design: The design of your portal should emphasize and simplify access to the docs. It should also help readers of a blog, or provide access to relevant documentation related to the article they are reading.
  • Optimize for SEO: Your engineers are not considering SEO when they create the docs. But docs are arguably the richest source of keywords associated with your product, and they make up the ecosystem your users live in. So there are countless opportunities to modify documentation language, or add content to dramatically improve SEO.

 

  • Update information architecture: The hierarchy of your documentation for the developer journey is often neglected. Developers need to look at the hierarchy of your documentation and immediately know within no more than two clicks where they want to be. Your engineers will organize the documentation in a way that makes it easy for them to get to particular API calls. But the organization could be completely different for users. That is why it’s important to spend time on the information architecture of your public documentation to maximize convenience for your users.

 

 

  • Add conceptual tutorials: There is huge value to your users if the documentation helps educate them on topics relevant to the functionality of your profile. For example, if it’s a Maps API, you should have a high-level article on the basics of geofencing. If it’s a natural language processing API, you should have a high-level article explaining the difference between entities and terms. (If you don’t currently know what geofencing or entities are, then you prove my point). Just because a developer is using an API does not mean they are experts. Educating them in a non-marketing way is important.

 

The takeaway

There are some logistical hurdles to integrating developer docs into your content marketing strategy. But they are doable, and some organizations are seeing that their documentation is the biggest organic traffic generator over anything else.

Fixate IO can assist with the creation, architecture and copyediting of developer documentation, and provide advice on ways to integrate each element into your developers’ release process and your marketing operations.


mm

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.

0 Comments
Would you like to share your thoughts?

Leave a Reply

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