Technically speaking: Improve Your Code With Documentation

on YouTube ↗01h 14m

" summary

Claims six actionable takeaways and that writing while building prevents future toil and support emails, with concrete examples: comments that explain nonobvious constraints for Google Publisher Tag, a failed open‑sourced WordPress bingo plugin later fixed, and containerizing a 2048 app to learn Docker. Recommends specific deliverables: good README checklist, step‑by‑step tutorials with transcripts, and release‑note templates, and emphasizes write as you code plus the practical habit goal six takeaways.

AI-written summary · about

" chapters (47)

1. 0:00Welcome
2. 0:22Agenda
3. 3:04Why Alexandra started a blog
4. 5:19Alexandra's goal
5. 7:11I am lost
6. 7:51Documentation is a tool
7. 8:46You are already writing
8. 10:37The kind of technical writing I do
9. 11:06Good docs
10. 11:33Cliffs Notes
11. 15:40Writing
12. 16:22Teaching CSS
13. 19:28Learning is a two-step process
14. 20:57Write documentation first
15. 21:46Writing is good for you
16. 22:33I love sprinkles
17. 23:00Confetti cake
18. 24:15Everyone agrees
19. 24:41Why are you creating documentation
20. 25:07Does your document exist to inform
21. 25:58Compliance
22. 27:05Why
23. 27:18Audience
24. 30:40Future Self
25. 33:26Reassignment
26. 34:21Internal documentation
27. 36:36Know your audience
28. 37:23The curse of knowledge
29. 38:29Spell out words
30. 40:12Define your deliverables
31. 40:25Write while you code
32. 41:31Google Publisher Tag
33. 44:53Bad Comments
34. 45:42Write a Readme
35. 47:02What Makes a Good Readme
36. 49:00Bonus Points
37. 50:14Step-by-step
38. 51:22Bad instructions
39. 53:36Templates
40. 54:15Release Notes
41. 55:02Bad Release Notes
42. 56:02Performance Improvement
43. 57:59Better Release Notes
44. 58:17You Can Now
45. 58:31X Now Does Y
46. 58:49X No Longer Does Y
47. 59:14Blog Posts

" related talks

• 51mTechnically speaking improve your code documentationAlexandra White · DevFest Lille 2022
• 52mTechnically Speaking: improve your code with documentationAlexandra White · Build Stuff 2019
• 46mTechnically Speaking: Improve your code with documentationAlexandra White · phpday 2020
• 49mExplain Yourself! Documentation for Better CodeChris Ward · LinuxCon + ContainerCon Europe 2016
• 28mImproving Your Documentation: A talk for developers who want to write stuff goodCharelle Collett · PyCon AU 2017
• 27mWrite Docs Devs Love: Ten Tips To Level Up Your Tech WritingMason Egger · PyCon US 2022
• 01h 24mWriting Documentation - Practices and TheoryLlewellyn Falco · Craft Conference 2023
• 35mThe Art of Documentation and Readme.md for Open Source ProjectsBen Hall · KubeCon + CloudNativeCon North America 2017