How to build an engaging developer tutorial

#devrel #documentation #tutorials

Developer tutorials can take a lot of time to build correctly so you want to get it right so you get value on your investment. Tutorials are one of the key ways you can help new people using your product to get started learning the skills they will need later. Reference documentation often lets you know what is possible and how it works, but tutorials are about guiding you through a problem to solve so that you can have a context that you understand and can help you learn the skills.

"A tutorial serves the user's acquisition of skills and knowledge -- their study. Its purpose is not to help the user get something done, but to help them learn."

Diátaxis documentation framework, by Daniele Procida

In my opinion, writing a solid tutorial for developers needs 7 key ingredients:

A clear scenario or goal to achieve
Contextual information (the 'why' of things)
Linear steps through the whole process
Visual elements to guide the user through the steps
References to allow for deep-diving into related documentation
Clear next steps to take in the learning journey
Code that you can copy!

#1. The scenario or goal to achieve

Something like "How to query the GraphQL API" or "How to add a block on the page" is not helpful to a user who does not yet know anything about your product or what steps they need to take to solve a problem. At the moment when they are starting, they don't know what APIs or features you have, so you need to write from a context of a problem they would usually solve.

For example, instead of "How to query the GraphQL API" you might write something like "How to create a product page" and over the course of the steps include the steps that show how to query the GraphQL API. This way the developer can see the context of when it makes sense to use a particular approach in a real-world scenario.

It also helps with your search optimization because now the content will have keywords around the GraphQL API but the title will be able to hit into the user context that people might be searching for.

Now, you might be under a constraint to use a specific title with certain keywords, but if you ground the actual content in a real-world scenario you can still achieve most of this goal by making it real for the developer.

#2. Contextual information

Just as having a scenario/goal can provide context to the user, it's helpful to explain the "why" of the steps in the tutorial. Before the user begins a series of steps, provide some context about what is about to happen and why the user needs to accomplish it. Then, as the developer goes through the steps, try to have key points where you callout additional context around a particular action. This allows the user to understand why a specific choice is being made, instead of just trying to learn a specific series of steps.

By having the context, the developer can then translate what they learned to other scenarios where that context might also apply. For example, in the "How to create a product page" scenario, there might be a step that indicates to provide an API key to request data about the product. You may want to include contextual information as to why the API key will add a level of security to your application and how it might be different in a production versus development environment. This information does not help the developer progress through the steps, but helps them retain the "why" of the step.

#3. Linear steps through the process

In video tutorials, a lot of the audio content can skip over details because the video can show the specific steps needed. When you want to use a written approach for a tutorial, you have to take all those little actions that the developer needs to take and represent them as a linear flow of steps. The user should be able to just read the numbered items and be able to accomplish the goal, without needing to consult a video or screenshots.

Your steps should also be numbered and be atomic. Try to avoid writing sentences like "Open the context menu, select the File option, and then save your changes". Instead, break up the steps as logically as possible. For example:

From the Context menu, select the File option.

Click the "Save" button to save your changes.

Each step should take the user one step closer to the goal. Avoid doing a chunk of work and then "rewinding" the user to an earlier state in the overall flow. The developer should feel like they are progressing towards the goal and not be made to feel like they've gone backwards.

#4. Visual elements

Product screenshots can be costly to maintain in tutorials, especially with B2B SaaS products where changes can happen regularly as continuous improvement is made to user interfaces. However, they have an extremely high value to new users who are evaluating your product offering. If you are building out a trial experience or are building out a tutorial to support a product evaluation workflow, screenshots, diagrams, and other visual elements are key to create an engaging piece of content that really pulls in the reader.

Screenshot from XM Cloud Tutorial on datasources

If you are creating a more reference-style series of steps for existing developers, this may not be as important to value as they often are experienced with the interfaces and the flow and need the content in a more condensed format.

If you have the possibility for clickable visual walkthroughs or videos, this can be another way to create an engaging visual way to learn.

#5. References to related docs

In all likelihood, a tutorial focused on a specific goal is only going to show one specific way of working with your product, while there may be dozens or hundreds of possibilities available to the developer for other scenarios. Your tutorial gives you the chance to expose documentation to your developers at a point in time where they are interested in learning and have some context around when it might be helpful, but with the choice to stay in their current flow and come back later. Many developers enjoy going off on a learning tangent and deep-diving into a topic to learn what else might be possible!

Linking to these docs inline is the easiest way to make it available, but having a list of references or 'further reading' is also helpful.

#6. Clear next steps to take

Similar to additional reading references, you want to give the developer a clear next thing to learn so they know where to go. You might have given them one solution, but they likely need to learn more, so this is your opportunity to create a guided path for them. At the end of a "How to create a product page" you might direct them to another tutorial named "How to update prices dynamically". The current tutorial gives you the context of the problems the developer is interested in and allows you to create a learning path that makes logical sense.

Always leave them wanting more!

#7. Code that can be copied!

When addressing a developer audience, the most critical piece that sometimes is missed is making sure the developer can copy the codeblocks from your tutorial. Using images or HTML-formatted text might look nicer but it makes an awful experience for the developer who is just trying to get through the tutorial and see how the code works. If you can provide a repository of working code, that's even better!

Ideally, your code block can be directly copied to an IDE, but also have formatting so that it is highly readable on your tutorial page. On my personal blog site, I can use a syntax highlighting code block to get it to look 'okay', but if you can do something fancier with your own custom component or using a third-party library that's even better! The below codeblock is formatted using Markdown:

import { Box } from '@chakra-ui/react';
import { ChangelogEntry } from '@scdp/changelog/types';
import ChangeLogItem from './ChangeLogItem';

type ChangelogResultsListProps = {
   entries?: ChangelogEntry[];
   isLoading: boolean;
   hasNext?: boolean;
   onEndTriggered: () => void;
};

const ChangelogResultsList = ({ entries, isLoading, hasNext, onEndTriggered }: ChangelogResultsListProps): JSX.Element => {
   return <Box>{entries && entries.map((item, i) => <ChangeLogItem item={item} key={i} loading={isLoading} isLast={i === entries.length - 1} isMore={hasNext} loadEntries={() => onEndTriggered()} />)}</Box>;

};

export default ChangelogResultsList;

Note: Above code from Sitecore Developer Portal GitHub repository.

What elements do YOU always include?

I always struggle with containing an article like this to a specific number of things. There are so many pieces that make a good piece of content! Did I miss any that you think are really key in technical writing? Or do you disagree with one of the ones I included?

Here are some examples that I think are very solid (including one I wrote recently). They don't necessarily hit all the pieces I mentioned, but I think they have a lot of the elements I've outlined in this article and can give you a look at the way different sizes of companies and different writers approach this problem.

React Tutorial: Tic-Tac-Toe: This one has a great scenario and provides lots of contextual information. The visual elements and code sharing is great too!
Otterize Workshop: A great example of linear steps and keeping the flow for the user so they know what they need to do next.
RedwoodJS: The Tutorial: Really great use of contextual information. I love the use of different call-out blocks to provide additional information.
XM Cloud Tutorial: How to Map Component Data Sources in XM Cloud: When I wrote this with my colleague Sebastian we focused on very clear linear steps with a lot of visuals and context and links to related docs.

If you want to see some technical writer's thoughts on this, these were some articles I found on the topic during my research that were really helpful in validating my ideas on the topic: