Marketing Writing and Your Docs

Most people reading this post are probably horrified by the title. What?? Docs are surely a purely technical exercise! My engineers write them! They should be BS-free!

First of all, your docs should 100% be BS-free, but so should every word you publish (or say) anywhere. Second, for an open source project your docs are very important marketing collateral. This is also true of any developer / software engineer focused tool. The docs are really important not just for people to figure out how to use the project / product, but also for them to figure out if it is worth their time to even get started.

The ReadMe

This is most obvious on an open source project’s ReadMe. A ReadMe is, at least at the top, a marketing document. It should state in exceptionally clear terms what your project is (aka your market category). It should be very clear about the circumstances in which the project is an ideal fit, and the circumstances in which it is not a good fit. It should outline the outcomes that users can expect from using the project. And it should list out what differentiated value the project delivers.

In other words, the ReadMe should convey the same information as your website’s homepage. The format is different, the exact words should be different, but the information you want to get across should be exactly the same.

Getting started

If the first page of your docs isn’t a ReadMe, but a ‘getting started’ page, you should include all the same information I just listed above. It should be brief, yes. But it should be there. Instead of just jumping into the how of getting started, make sure a visitor knows why they would want to get started.

The way many developers navigate websites is to click on the ‘docs’ link at the top of a website without scrolling down. So they won’t see any of the information on your homepage unless you put it on the first page of the docs. And this is information they need to get, so they can make an educated assessment of whether or not the project/product is right for them.

Throughout the docs

The ReadMe or Getting Started pages are the most important ones when it comes to getting your message into the docs, but ideally you’ll have value-focused, outcome-focused language sprinkled throughout your docs. Every time you explain how to use a feature, start by describing the outcome the feature delivers and how that outcome fits into the value the user is looking for.

Developers read docs, and they read them carefully. They will use them not just to learn how to use your project or product, but also to form an opinion about what the project does and whether or not they should care about it. If you don’t include benefit and value-based messaging in your docs, you’re wasting an opportunity to get your message across. Because even the most technical software engineer is still a human, and still needs you to help connect the dots between technical features and outcomes and values they’ll get.