Docs as Marketing

As customers continue to take the lead in their buying journey, the value of clearly-written documentation is quickly rising.

Last week a friend asked me for a list of articles and presentations that had shaped my thinking about how marketing works. The list included pieces about how brands live in people’s heads, classics like Christensen on jobs to be done, and a presentation from Gartner analyst Brent Adamson on how B2B sales has changed over the last decade.

The gist of Adamson’s research is that B2B buying has shifted from being sales-led to customer-led. Buyers are spending more time researching on their own and with their teams and less time talking directly to vendors. That doesn’t mean sales doesn’t matter. On the contrary, it’s even more critical that salespeople make the most out of the sliver of direct prospect interactions that remain.

It also puts an ever greater emphasis on your website. The largest bucket of time in B2B buying is “Researching Independently, Online.” While some of that time is spent on Google and comparison sites like G2, much of it is also devoted to vendor websites. It’s been interesting to watch the shift in the content on B2B websites over the last few years for this reason. One of the things I’ve noticed, for instance, is that more and more vendors include a competitors page where they explicitly call out their points of differentiation. That’s clearly a result of this shift to more customer-led buying.

With that said, probably the most significant shift I’ve seen is the movement of product documentation from something that you put behind a login wall to something that you include in your top nav. A few examples below (including our own nav):

Where your docs are in your nav says a lot about how important they are to your buying process

Looking at those companies, it’s easy to say that they’re all very developer-focused, and it makes more sense to put documentation front-and-center when your customer is an engineer. But to that, I’d ask, “why?” You might say, “well, of course developers don’t want to talk to sales and would rather just learn from the docs and get hands to keyboard as quickly as possible.” To which I would probably just nod along and raise my eyebrows a bit.

What developers are doing today, we’ll all be doing tomorrow. I’d argue that the thing about docs is that they’re fundamentally different from marketing in that they’re written for users, not buyers. They don’t presume to know what you’re most interested in or try to sell you something you may or may not need. They just help explain what a product can do. Here’s how Jeff Lawson, CEO of Twilio, described docs on a recent a16z podcast:

Now, I remember, back to the early days when I was a developer. I would do a Google search, "this looks good … okay, how do I get started?" And you click into it and it would say, "contact sales." And, you know, "if you sign an NDA, you can read the documentation," and you'd be like, “okay, back, nevermind, I don't want that.” Because for a developer, documentation is the ultimate marketing. Yes, every company has a marketing website that's pretty and hand-wavy. But at the end of the day, the documentation of an API is the perfect description of what that product does. It literally describes every in and out and what the product does. And you don't have to believe a salesperson, you don't have to look at a slide deck.

Necessity led Twilio and the like to put their documentation front and center. But the underlying truth—that prospects want to know exactly what a product can do in the most straightforward language possible—is pushing more companies (like us) to make documentation a central part of websites and content.

That’s the “why,” but what about the “how”? As someone who has done lots of docs writing, here are some principles I try to live by. Some of them are general rules of writing, and some of them are specific to producing good docs.

Clearly written and to the point. The following quote comes from the famous book Elements of Style and is something I try to adhere to whenever I write: “Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all sentences short, or avoid all detail and treat subjects only in outline, but that every word tell.” To add to this point, always write documentation for your user. Even though I’m arguing it’s good marketing, try not to let that seep into the copy. The power is in the focus.
Visual where possible. This one’s pretty simple. Especially when you’re documenting software, including visuals, GIFs, and videos can make a world of difference when it comes to comprehension. It’s critical to remember that not everyone learns the same way, and offering multiple modes will help ensure your point is communicated.
Skimmable. I once had a boss who wouldn’t look at any Keynote presentations unless the slides were indented properly to indicate sections and subsections. While it seemed a bit crazy at the time, his point was that you need to design things to be easily skimmed. Write the Docs, which makes an excellent repository of documentation about documentation, writes, “Structure content to help readers identify and skip over concepts which they already understand or see are not relevant to their immediate questions.” That means using headings, links, lists, paragraphs, and bolding, amongst other things.
Up to date. This is one of the most obvious and most often forgotten rules of good documentation. Documentation that is no longer correct can be worse than having no documentation at all. “It’s impossible to trust documentation that is routinely out-of-date so developers end up going back to the humans that contain the most update date information. This reinforces the notion that writing anything but code is a waste of time and keeps system knowledge locked safely away in human brains.”

You'll never go wrong with Elements of Style

Hopefully, that’s helpful. The last thing I’ll add is to reinforce the value of owning your docs. In deciding where our docs should live, we decided to house them as part of the site. This is part of our general focus on first-party data and research-led growth. This might create some headaches down the road as we need to integrate the docs into a ticketing system. But it also gives us complete control of the data around how our documentation is being used and by whom. That data can provide valuable signals (through Variance, of course) that can help drive sales and customer growth.