Writing a perfect technical tutorial

on YouTube ↗38m

" summary

Shows the actual authoring workflow: starting from code notes and a Markdown baseline, followed by a review schedule and who to include. Gives concrete examples and tools used—Twitter API to Google Sheets, pandas, Google Sheets scripts, AWS Amplify, AutoML and Twilio, GitHub Actions—and reports outcomes: traffic, repo clones, PRs and one tutorial that inspired six posts. Explains how success is measured (people who built things, support links) and how to keep code current so the tutorial still works.

AI-written summary · about

" chapters (20)

1. 0:00Start
2. 2:06Why write a tutorial?
3. 3:33What makes a good topic • A topic that's been coming into support often • Anything you got stuck on • Something you are excited about • Anything that you built that you are proud of
4. 5:56Where do you want to publish this tutorial?
5. 6:53What is the goal of your tutorial?
6. 7:12What do you want the reader to walk away with?
7. 8:13What is the story you are trying to tell?
8. 8:37Create a baseline that you can refine and build into a tutorial
9. 10:02Does your code have a narrative structure?
10. 10:37I use a markdown file while I am writing a code sample that I can edit later on
11. 11:03I've also used a screen recorder to record myself writing code and used that to create my baseline
12. 11:27Examples
13. 11:57Sending a response from the Twitter API to a spreadsheet in Google Sheets
14. 16:30Review process
15. 16:59Try to find reviewers who a mix of your peers and subject matter experts
16. 17:42Do you know anyone who is part of the audience you are trying to reach?
17. 18:55Be mindful of your overall vision during this part of the process
18. 20:26After you publish your tutorial
19. 22:23Refreshing your tutorial as it gets out of date
20. 25:19Conclusion

" related talks

• 01h 14mTechnically speaking: Improve Your Code With DocumentationAlexandra White · PHP UK Conference 2022
• 39mTackling Technical WritingAlaina Kafkes · RubyConf AU 2018
• 43mUseful and Beautiful Developer Docs and How to Create ThemJohannes Dienst · JCON WORLD ONLINE 2023
• 29mDocumentation: The Missing PiecesAdrienne Braganza Tacke · JSConf Budapest 2022
• 13mTechnical documentation – how can I write them better and why should I care?Hila Fish · LeadDev Berlin 2022
• 46mSave a Dev, Write Documentation!Sarah Haim-Lubczanski · Devoxx France 2024
• 35mThe Art of Documentation and Readme.md for Open Source ProjectsBen Hall · KubeCon + CloudNativeCon North America 2017
• 52mTechnically Speaking: improve your code with documentationAlexandra White · Build Stuff 2019