Write the Docs: Writing a perfect technical tutorial – Jessica Garson

Catherine Heath | April 27, 2021

This talk at Write the Docs Portland 2021 was given by Jessica Garson. Jessica works for Twitter as a developer advocate. She spends a lot of time creating tutorials, so fittingly her talk was about how to write a successful technical tutorial. 

Why write a tutorial

First, Jessica talked about the reasons behind why you might create a technical tutorial. 

Why write a tutorial? The point is to guide the reader to complete a specific action. It’s a way to really get someone started to do something, or help someone do something more easily. You help others avoid the stress you had to experience. Tutorials helped Jessica learn to write code and then very quickly led to her writing her own tutorials.

What should tutorials be about?

Jessica highlighted a few great sources for tutorial topic ideas:

• Something that comes into support often

• Something you got stuck on

• Something you are excited about

• Anything you built that you are proud of

• A good story to tell.

Jessica's basic rule of thumb is anything that you can’t easily google the solution for is probably a good tutorial. 

How to write your tutorial

Once you've decided to write a tutorial, Jessica suggests you decide where you want to publish your tutorial, since this impacts the audience you'll be writing for. Options might include:

• A developer website

• The company website

• Medium

With that overall audience in mind, Jessica suggests a few additional questions to help you shape the tutorial:

• What is the goal for your tutorial? What are you trying to help the reader accomplish after reading this tutorial?

• Who is your audience? Could be beginner developers, mid-level developers, etc. A beginner audience will need a more guided journey, whereas a more advanced developer might just have the topic and some resources. 

• What is the story you are trying to tell with your tutorial? Did you solve a problem and feel really excited about that, or are you trying to help others solve the same problem you struggled with?

Once you've thought about these questions, you're ready to start writing your tutorial. 

Create a baseline for your tutorial

There's a particular way that you can go about drafting your tutorial, which Jessica elaborates on. She calls it creating a baseline.

She suggests that you think about taking notes while writing code, which you can then more easily turn these into a tutorial. Does your code have a narrative structure? This can be turned into a tutorial. 

Jessica uses a markdown file while she’s writing a code sample that she can edit later on, which makes a great baseline. She’s also used a screen recorder to record herself writing code and used that as a baseline. 

Jessica showed us some examples of tutorials, including this one on how to detect hair color with AutoML, MMS, and JavaScript. 

Set up the review process

Writing a tutorial is not a set it and forget it process. You need the feedback of others to help you get to the finished point. 

That's why Jessica suggests you have a review process for your tutorials that includes reviewers who are a mix of your peers and subject matter experts. She makes a review schedule to keep the review process organized. 

She tries to figure out who can help her analyze what she has and take it to the next level. Do you know anyone who is part of the audience you are trying to reach? These can make good reviewers. Before she joined a formal team, she often had friends reviewing her writing. 

Though reviewers are helpful, Jessica also warns not to let the reviewers dominate your tutorial. Be mindful of your overall vision during this part of the process. She likes to use track changes to keep track of the suggestions from her reviewers. It’s your tutorial and your story that you’re telling, so that means you don’t have to accept all feedback from the review process. 

Once your satisfied with the results of that review process, publish your tutorial!

Post-publication

Publishing your tutorial is not the end of the game, either.

After you publish your tutorial, Jessica says that it’s important to measure the success of your tutorial. Some measures for this are tracking the number of people who have clicked on your link, or total views. She said she finds this to be a less useful metric than tracking the number of people who said that they solved a problem because of her tutorial. 

Other measures might be:

• How many people are asking questions in forums based on this post?

• How many people have cloned the repository that is used in your tutorial?

These can be more telling metrics than simply counting page views.

Jessica also noted that you need to keep returning to your tutorial to make sure it doesn't become outdated. A lot of things can change as time goes on, so make sure to check your tutorial still works.

Final remarks

One of our favorite points was one of Jessica's last, which is that once your tutorial is out in the world, you might be able to harness its content in other ways. Think about how you can recycle your tutorial into a conference talk, a video, or a livestream, and build it into something more. Tutorial content can be a bit like an ecosystem that evolves over time, rather than a single isolated product.

(And hey, who knows? Maybe that tutorial topic would make an excellent Write the Docs presentation!)

Watch the full talk here. 

{{snippet.authorCatherineHeath}}

{{snippet.Disqus}}