Skip to content

Two Things all DevRel Programs Need!

Two men grabbing a propeller on a plane trying to get it started

I often get approached by companies, from startups to large enterprises, to give them advice on their developer relations. One of the things they want to know is where they should be focusing their investment. My analysis always begins the same way – I go look at the developer focused portion of their web site.

Right off the bat, I am looking for two things:

  1. Good reference documentation
  2. A great Getting Started (also called a Quick Start guide)

You might be saying “Wait, you are saying that is all I need?” What I am actually saying is those two pieces of your DevRel program are necessary but not sufficient.

Actually, the most important feature is a well-designed product. I am leaving it out today’s discussion because developer relations has limited control. Today’s discussion is focused on things your team controls and can prioritize.

One quick note, I am going to use project and product interchangeably. I know they are not the same thing but I think the lessons are transferable and it gets tiresome to always read “project or product”.

Now, with that covered, let’s dig in!

Seriously, only 2 DevRel Features?

Reference documentation and a great getting started guide just happen to be the top two things you need before everything else. Just like oxygen and water are the top 2 things required for human survival, without these assets your DevRel efforts are wasted. Until those 2 items are great, reduce your commitment to everything else. 

These are not the only things you are going to need to build and do, but until they are done focus on them exclusively. If your devrel program is already up and you are working on other things, take a moment to look at these two items and see if they shine. If not, reallocate work to either producing them or getting them to be delightful.

But Why These 2 DevRel Features?

Your overall goal is to make users successful and happy on your platform. You can think of developer relations effort as a house party, and you want the developers to hang out. Without these two items at your “house” developers are going to have a bad experience before they even make past the entryway.

You spent all that time, money, and effort to get the developer to show up at your house party, make sure they are amazed and comfortable as they mingle.

Reference Documentation

Reference documentation means the low-level technical documents – JavaDoc, Pydoc, OpenAPI spec… Developers tend to be impatient and are going to want to self-serve. As they try to build something with your project they are going to have to understand, explicitly, how to use the bits and pieces. Without good reference doc, developing with your stuff is painful and frustrating.

You have probably experienced this just like me. I am reading some API spec or object document; I think “I need to create a kitten”. The method is called makeAKitten(wish, money), or make_a_kitten (wish, money) if python is your jam. I get excited that there is a function call that seems to do exactly what you need. I go to the reference doc to learn more, and it looks like this:

makeAKitten(Wish, Money) – makes a kitten 
        Wish – wish object
        Money – money object
        Kitten – kitten object

While technically there is documentation, there is no context or clarification that helps me to understand what is going on. How is this function intended to be used? Does it require some other method being called before I can make a kitten? What are the units for the wish and money, do they have restricted ranges? I have not really learned anything about this method call that wasn’t already obvious from its signature.

Making good reference doc is going to require cooperation and work from the engineers. They will be the ones responsible for the first draft of this documentation. There should be a tech writer or advocate who goes over the doc as part of the review process.

Since engineers will be involved, I highly recommend using a Docs as Code approach with your reference document. The best is to use the built-in documentation system, such as JavaDoc and OpenAPI. There are plenty of platforms for making good reference doc such as Redocly, Read the Docs, Docusaurus, Sphinx, and many others (be aware, most lists of systems are written by documentation products, take with a grain of salt). Find and use the one that’s right for your product and team.

With this completed, we can turn to your next fundamental piece, the Getting Started Guide

A Good Getting Started

It is amazing to me how many developer sites do not have a getting started, or if they do, it is of poor quality. Please don’t tell me your guide looks like this:

  1. Installation
  2. Description of things you can do
  3. Where to go read and do more

Developers have limited time, and you only get one chance to engage them. If they leave with a bad impression, you will probably never see them again. Why waste all that time, energy, and money to finally get them to look at your site only to leave frustrated.

Developers have been trained to look for a Getting Started guide to give them a solid jumping off point for the rest of the documentation and development.

Let me make it really clear why you are writing this guide:

  • This is you curating a great experience using your product to solve a problem, A SIMPLE PROBLEM
  • You want to make sure the user has a good foundation to understand and work with the remaining content you create for them

I need to repeat this because this is a frequent mistake.

Getting started guides show ONE SIMPLE PROBLEM and not complicated and advanced scenarios

Use your tutorials and samples to show more robust usage.

What Makes a Good Getting Started Guide

Here is the layout of a good getting started guide:

  1. Welcome
    • One sentence on the problem your product solves
    • One or two sentences on what they should expect to know by the end of the getting started.
  2. Key Concepts
    • These are terms or ideas particular to your product
    • They may even cover basic ideas for people new to the field, but if you do that let experienced developers know they can jump ahead to the next section
  3. Pre-requisites
    • Put all needed pre-requisites here, only make them suffer through this pain once
    • For dependencies outside of your project, make sure to link to the outside project’s home pages, their installation, and getting started guides
    • For complicated pre-requisites you should probably write an installation guide ensuring it works with your project
    • You want them to have to spend the LEAST amount of time possible here
    • You cannot let them fail here. Better to say “go learn this thing and then come back” than let them struggle and get frustrated installing a dependency
  4. Downloading the bits
    • One for each of the major OS’s
    • Or if it is code based, at least one for the top 4 programming languages
      1. JavaScript
      2. Python
      3. Java
      4. If you are enterprise focused the C#
      5. If not, then pick one of the hip new languages (at the time of this writing, that would be Rust)
  5. Installing for all the download bits given in the previous item
  6. First thing to try with the product
    • This is a test to make sure everything is working
    • You are trying to create the shortest possible path to “That was nice”
    • It should be simple as possible to understand and focused on showing that everything is installed and ready to go
    • If they need to get a key from your web site, go above and beyond in making sure your instructions show them exactly how they get it
      1. Use screenshots
      2. Keep them updated
    • Make sure to link to ref docs that help them do the thing, this will help them learn about the reference docs.
  7. Solve one simple problem with your product
    • Make sure the code for this is in GitHub
    • The app should only be as complicated enough to show the one thing – no more.
    • It’s best if you can make the one thing easily grow to include your tutorials and samples
    • Test this code often, IT HAS TO WORK
    • Give some troubleshooting tips for those who can’t get it to work
    • Again, liberally link to your reference doc in this section too.
  8. Wrap up
    • Give them kudos for the cool thing they just did.
    • You want to make it clear of the benefit you just gave them
    • Show them how to join the community and get help
    • Point out the purpose of your other content (of course with links)
    • Suggest some things to try – usually linked to a tutorial or sample
    • End on a positive note

Wrap up

I hope you can now understand why I think reference doc and a getting started guide are the two most important things you must nail from the beginning. I am not saying they are enough by themselves, but without them the rest of your content will suffer. Not only will the content suffer but so will your:

  • Support staff
  • Sales staff
  • Marketing efforts
  • most importantly, the user

You don’t have to do these two items to the exclusion of all other DevRel activities, just make sure these two items are a major focus.

Your reference doc and getting started guide form the entryway to your developer relations house, be sure to make a good impression.

The guidance I give above should help you get on your way. If you want more in-depth help with these two items, please do contact us. Whether you want an assessment of your content or help creating the content, you can rely on the experience of Tech Raven Consulting.