I clipped the tiny electronic device to the top of my guitar, pushed its button, and plucked a string. The screen delivered a note I did not expect. After some frustration, I picked up the small pamphlet from the tuner’s packaging. My new toy was in violin mode. A quick switch to guitar mode and it worked as expected. Three cheers for whoever wrote that compact manual that shipped with my guitar tuner. They had no control over the product itself, but their efforts helped me use it.
Too often, developer experience is misunderstood as solely product changes. It’s the onboarding when a developer first signs up. It’s the sandbox or credential generator. It’s the SDKs or portal platform or some other piece of technology. Yes, it is.
But it’s also the words, the way they map the journey, and how they understand the documentation audiences. Developer experience is made of content and documentation teams have a significant ability to influence important developer interactions. This post will share three areas to review and refactor to improve your developer experience—without any product changes.
Most dev tools are designed to be flexible. They don’t require a specific tool set, so they can plug into any team’s workflow. APIs, for example, use conventions and standards that allow developers to quickly integrate a new service. Many developers still prefer more guidance through the experience. You can encourage them with documentation that shows you understand their tools and workflow.
The most common way to position your product to a developer is to show how it’s used with their programming language or framework. It’s true, the code to integrate an HTTP call in Python, for example, is trivial for a Python dev. But you can remove the effort to connect the dots when you create Python-specific documentation. Then, take it a step further with Django and Flask framework tutorials, much like Render does:
Don’t skip this section if programming languages aren’t relevant. There are other tools that you can use to focus your documentation:
- Deploy tools can use CI/CD products like Jenkins and Circle CI
- Data analytics can show pipeline tools like dbt and Airflow
- Cloud orchestration services might segment docs by databases
When you’ve determined the frame of reference you’ll employ, decide which technologies you’ll support. You might choose different depths of integration. Some will have many examples and others may only get a single doc to start. Again, your ability to produce and maintain these docs will determine what you publish.
In many cases, you’ll be able to maintain the language focus throughout the documentation. The Plaid API reference, for example, can be viewed through the lens of six programming languages. One of the most important areas for this language, framework, or tool focus is during a developer’s first experience with your product.
Documentation is more than the black and white facts of how to use a developer product. If you only supply an API reference, for example, you’ve missed out on the opportunity to connect the dots between its various endpoints. Documentation teams can improve developer experience by intentionally adding content that enables the entire developer journey.
The most obvious—and still missed—piece is a tutorial focused on the very first experience. Sometimes this is measured in the “time to hello world.” Most documentation should be framed around this first experience, ideally with a language-specific tutorial.
Frequently, we see documentation sites without any getting started material. Or, almost as bad, we’ll see multiple getting started journeys with different end results. This lack of clarity can confuse a developer’s first experience with your product. Put a lot of energy toward defining your hello world moment and remember that it is only the first experience, not the entire experience. Trim out unnecessary steps and find ways to simplify the tasks you can’t avoid with copy-paste code or complete repositories.
Anything you’ve removed from your initial experience might be incorporated into the next phase of the journey. Developer experience does not end at hello world. In fact, for developers to continue to use your product, you’ll need to get them to first success. That means an obvious next step—or choice of next steps—after the initial experience.
The next step will depend upon your product, but here are some common documentation pages to link at the end of your getting started tutorial:
- Tutorial for deeper integration into their code
- Walkthroughs of specific use cases with your product
- Sample apps of varying depth to show real-world usage
Naturally, many of these will also need links throughout your documentation, not just as part of the initial experience. This sort of contextual documentation is often missing—or difficult to find.
Now that you’ve streamlined the first step or two of the developer journey, it’s time to acknowledge a reality of large documentation sites: the bulk of your content resources are used by developers in their subsequent visits. That is, while that first experience and success is important, it’s quickly forgotten if they were frustrated by their last interaction.
Every documentation team knows that organizing various types of content is a much bigger topic than can be covered in a small section of a single blog post. Instead, we’ll look at one way to consider the types of content in your documentation.
Many Google Developer sites, like Drive shown above, use “Guides” and “References” sections. These are great examples of two primary ways to segment documentation content:
- Function: what is supported and how it works (reference content)
- Context: how it is used and why it matters (guide content)
Though getting started tutorials are mostly context, they include some function, as well. In fact, most documentation will be a mix, but the mostly-function-focused content is usually easier to spot. Separate it out, then take stock of the mostly-context content that remains.
You might choose to further divide contextual documentation, as Google has with “Samples.” Other common solutions are to subdivide content by content category, such as use case or area of the product.
You may be overwhelmed by the many projects to add to the documentation backlog. But this is far better than the alternative of waiting for product updates to improve developer experience. Both are important, but content-focused efforts typically take less time.
As a next step with your developer experience, assess the current state with our DX Quiz. We’ll guide you through 13 criteria and deliver a free DX score you can share with your team. Then you can start to improve your experience, with an emphasis on the most important areas to help developers be more successful with your product.