Technology Platform Content Strategies

A frequently-overlooked aspect of managing a platform technology product is creating a sensible content plan and executing on it effectively. This is not what you’d call a sexy topic: In a lot of ways, technical content is to a platform as horse manure is to a farm. Very few people get excited about working with it, but if you don’t bring yourself to do it, things won’t grow as fast.

Having produced content to support a variety of technology platforms for more than a decade, I’ve come up with a few very general strategies for how to approach this.

The first strategy is Identify and Develop Reference and Narrative Documentation. Reference documentation is the bare-metal documentation that anyone would need to use your platform. This is the absolute minimum you can do in terms of documentation and content — without it, nobody will be able to figure out what you’re doing. Narrative documentation is far less dense than reference documentation; a good example of the difference is the Java tutorial for exceptions versus the reference documentation for the Exception class. Typically, reference documentation is delivered by your engineering team; narrative documentation is provided by technical documentation specialists.

The second strategy is Build Content Out To the Last Mile. It’s not enough to run an automated documentation generator on your source code and upload it to a web server, or even to set up a wiki and declare victory. You have to create technical content that is going to speak to software developers where they live, and generally that means writing to some kind of programming language. The languages you target will differ depending on several factors, including the programmability model of your platform, the amount of resources you have to devote to content, and the expected number of developers using each language you want to address.

Some examples: Let’s say you’re Palm and you want lots of developers to adopt WebOS. You have something of a head start here because you’re leveraging a single, commonly-used language (Javascript) and other web-centric technologies that a lot of web developers use. But there’s still a Last Mile for you: you’ve got an SDK, a Javascript framework, and a bunch of paradigms that are unique to mobile development.

On the other hand, if you’re a web services platform or some sort of back-end product, your Last Mile strategy is a little more complicated because you’re not tied to any particular programming language. That means that your Last Mile is the all programming languages used by your current and prospective developers, multiplied by the different pieces of narrative content that addresses each of those languages. I like to arrange this in a grid, like this:

Language Getting Started Guide Authentication Tutorial SDK Others
Java Done TODO Done
PHP Done TODO Done
C/C++ Won’t Do Won’t Do Won’t Do
Python Won’t Do Won’t Do Won’t Do
Ruby Won’t Do Won’t Do Won’t Do
Others Won’t Do Won’t Do Won’t Do

Making this into a grid turns it into a handy two-dimensional task list. It also informs where you devote resources (and potentially how you hire people; when we realized that PHP was important at eBay in 2004, and we had exactly zero PHP content, I hired a PHP guy pronto).

There’s a lot here, but the good news is, you only have to fill in each cell in the grid once. To manage resources, you are also likely to draw a horizontal line somewhere on the grid; languages below that line don’t get direct support from you (although you can graciously accept support from the community for edge-case languages that you can’t or don’t want to support directly). But the number of languages that you choose to support should exceed one (this was a serious problem in Facebook’s platform content until very recently).

Also, as you add major new features to your platform, you will of course add new columns to the content grid so that you cover your new features in all the languages that matter.

All that said, it’s also possible (even common) for platform technology organizations to over-plan their content strategy. This isn’t quite the same as what software architects refer to as “analysis paralysis,” but it feels the same. When you hear things like “we want to make sure we specify exactly what content we’re planning on publishing before we create a system to manage it” or “we don’t want to publish anything until every piece of content is ready,” these are signs of an over-planned content strategy. Best in this situation to develop the content you have, get it out there as soon as possible any way you can, and iterate on it frequently in collaboration with the developers who are using your platform.

This process supports a few tenets of the Platform Manifesto: actively managing platforms, nurturing communities of users, and providing self-service access.