Great Developer Documentation Is Your Best Marketing

I am sure you have all heard the saying, “Developer’s don’t like being marketed too.” And, yes it is very true. We detest content that uses words like fast, easy, simple, evolution. You know those weasel words that mean absolutely nothing but are meant to summarize a complex technical capabilities into something aspirational. For developers, it doesn’t work.

Developers are tasks with building complex solutions using multiple technologies, each with different dependencies, changing client/business requirements and making it work at scale. Imagine marketing a new bridge construction technique to a structural engineer by leading with fast, easy, simple.

Instead of spending time and money on marketing campaigns for developers, spend it on your documentation. To developers, great documentation is your best marketing tool. Documentation is often the first place developers will go on your website to learn about your product capabilities. Use this as an opportunity show them how your product can help them solve problems and build solutions by sharing as much detail as possible, and ideally get them hands-on to try it out for themselves.

So what makes great developer docs? Here are five things I believe will make your docs stand out and help you grow your developer adoption.

Quickstarts

Quickstarts should a stable for every developer portal. They are simple getting started tutorials which should take no more than 5 minutes time for a developer to try out your product. Twilio enshrined the idea of a 5 minute demo in any event or setting in which we presented at. We used Ahoy World as a homage to the original Hello World from Kernighan and Richie. Today, QuickStarts are ubiquitous in developer docs. Where things often miss the mark however is not providing developers direction once they complete the Quickstart. By its nature, a Quickstart is just a beginning. Great developer docs take developers on a learning journey once capturing their interest.

One other important point to note in relation to QuickStarts is that a Quickstart should also be used by DevRel and product teams to improve the product and API design. If you can’t create a very short starter demo because you have to mess with API keys, installing a bunch of dependencies etc, spend the time fixing the product experience first.

Developer Lifecycle

Continuing on the notion of providing developers a next step after the Quickstart, overlaying some form of developer lifecycle on our docs (and overall enablement) is a great way to structure learning content in a way which does not overwhelm users, and offers information and guidance as they need it. Vue.js is a great example of breaking down the primary activities developers will perform with their libraries, beginning with help to get started and essential requirements in building an app.Then, as developers become more proficient and are getting ready to launch their apps into production, they structure their document to provide information on more advanced topics such as scaling up, in depth details on APIs and components, and best practices. Streamlit Docs another great example of overlaying a developer lifecycle with a very simple Get Started - Develop - Develop framework.

Interactive Code Samples

My favorite feature of any developer docs sites is when there are interactive code samples and snippets for me to try out, and modify. The ability to have interactive code samples allows developers to immediately try your service and make it their own. No one does it better than Stripe. The Stripe docs let you sign in to edit requests, but best of all offer a fully functional interactive shell by tapping on the bottom right corner of any docs page. Once opened developers being up the API explorer to construct the calls they want providing a fantastic example of actionable learning vs trolling through API documentation.

Stripe’s interactive CLI is the gold standard in developer docs

This idea of interactive samples has taken a big leap forward recently thanks to Google Collaband Jupyter Notebooks. I’ve leveraged both of these services, and CodeSandbox to run online and in-person workshops. The huge benefit is that it eliminates the hurdles of local environment configuration for dependencies and lets developer jump straight into getting hands on with your product. I can’t tell you how many times I’ve spend 20+ minutes of an hour workshop trying to get an attendees laptop to install a library which their IT configuration refuses to allow.

Open Source

At Twilio we added the ability to rate the page from 1-5 stars. This was used to prioritize which pages needed updating, and influenced the overall Net Developer Score used to track developer sentiment. Github does something similar allowing you to rate with a thumbs up/down whether you found the docs page useful or not. And, Github took it a step further by encouraging developers contribute through a pull request if they see an error or think you can add additional insight. This idea of open source documentation is even more prevalent in companies founded on open source. Airbyte for example includes all of their documentation in a public GitHub Repository and actively encourages contributions.

Github allows you to rate and contribute to every page

Well Structured

Similar to developer lifecycle, well structured docs site manage to take a complex suite of tools and lay out all of the information in a very logical and easy to navigate experience. No one does it better than Docker for this. Compare the Docker experience to that of say Microsoft and you instantly see what I mean.

Microsoft’s approach to structured docs leaves a lot to be desired.

Docker provides a well thought out structure making it easy to navigate

For companies with a less complex product landscape, I’d suggest relying on a more of a developer lifecycle model to structure your documentation. As your product surface area grows and you start targeting different personas structuring your docs across audience and products becomes increasingly important. Google is a perfect example here. They provide subdomains for particular audiences such as android developers, but also do a pretty good job of organizing the overall developers.google.com site by using a well structured Product dropdown, product and use-case/platform tiles.

Summary

Great documentation allows developers to try out your product without jumping through a bunch of sign up hurdles. It allows developers to get started quickly and have a path to expand their knowledge as their experience grows with your product, and they want their voice to be heard by supporting feedback loops such as ratings and contributions. Successful companies understand that documentation is often the first experience a developer will have of your product. They want to know if it will solve their needs today and in the future. Well structured and modern documentation is the best marketing you can do to achieve this.