Jessica Garson - Writing a perfect technical tutorial

A strong technical tutorial isn’t measured by clicks alone—it’s built to get a specific reader to complete a specific action, and then it’s maintained as the underlying tools change. Jessica Garson, a developer advocate at Twitter, frames tutorials as a practical bridge between “I’m stuck” and “it works,” drawing on her own experience learning by following directions and later writing to share the same kind of momentum with others.

Garson’s starting point is motivation and topic selection. Tutorials are worth writing because they guide readers through a concrete workflow—often the exact moment someone hits a wall. She gravitates toward topics that can’t be easily solved by a quick search, using that as a rough filter for what’s likely to be genuinely helpful. She also recommends choosing a story worth telling: a personal problem solved (like her “parking problem with python” example), an approach she’s proud of, or a remix of someone else’s idea that adds a new angle. When she’s deciding what to write, she also thinks in terms of audience fit—beginner, mid-level, or advanced—because that determines whether the tutorial should feel like a guided recipe, a code-centric walkthrough, or a resource-first overview.

Before drafting, she urges writers to decide where the tutorial will live—company documentation, a company blog, dev.to, Medium, or similar platforms—because publication location shapes the audience and therefore the writing style. Then she sets a clear goal: what the reader should be able to do after finishing, and what level of developer they are. She even treats the tutorial like narrative structure: either it’s about solving a problem, or it’s about preventing others from repeating the same failure.

For drafting, Garson emphasizes building a “foundation” first. Her method starts with notes captured while writing code—often in a notebook—then turning those notes into a skeleton that can be refined. She uses Markdown as a working document, and she leans on the idea that code can have narrative flow: functions can act like paragraphs, and docstrings can make the sample readable as it develops. She also mentions recording her process with a screen reader as a way to spot mistakes and clarify what a reader would need to follow.

Garson highlights examples of effective tutorial styles: remixing a colleague’s Google Sheets approach to send Twitter API data into spreadsheets; a Twilio tutorial on detecting hair color with AutoML and text messaging that uses engaging visuals; an AWS beginner guide that’s long but step-by-step and includes video; and a short GitHub Actions explainer that uses a GIF and fits into a larger series.

After the first draft, she treats review as a craft step. She builds a review schedule, chooses reviewers by role (peer, subject-matter expert, and beginner), and—crucially—keeps an eye on her original vision so helpful edits don’t dilute her voice or goals. Once published, success is tracked through outcomes: people who report solving the problem, inspired follow-on work, forum questions that indicate engagement, and even pull requests to accompanying code. Because technical content ages quickly (APIs get deprecated, endpoints change), she recommends periodically re-running the tutorial, updating it, and sometimes reposting refreshed versions. Finally, she encourages recycling: turning tutorials into talks, videos, live coding sessions, or conference submissions—treating each tutorial as part of an ongoing content ecosystem rather than a one-off post.

In Q&A, she adds practical guidance: screenshots and UI references can become outdated, so she uses them lightly and prefers approaches that won’t break when buttons move. She also reiterates that even without robust analytics, writers can track indirect signals like how often links are referenced in support channels and whether readers reach the end of the article.