2022-07-15 –, Wicklow Hall 1
Tutorials, blog posts, and product docs help developers learn. From our favorite tutorials to bad product docs we all consume technical writing. But what makes for good technical writing? In this talk I’ll share 10 tips and tricks to improve your technical writing skills to help your readers succeed
Think of that feeling you get when you follow an online tutorial or documentation and the code works on the first run. Now think of all the hours spent wasted following broken, outdated, or incomplete documentation. From our favorite tutorials to bad product docs we all consume technical writing. Tutorials, blog posts, and product docs help developers learn new things, build projects, and debug issues. But what makes one tutorial better than another? In this talk I'll discuss how you can write the documentation that developers love and I’ll share 10 tips and tricks to improve your technical writing.
Outline
- Introduction (1 min)
- Why is Technical Writing Important? (4 min)
- My Top 10 Tips to improve your Technical Writing (20 min)
- # 10 - Make Your End Goal Clear
- # 9 - Don’t Be Overly Verbose
- # 8 - Inclusive Language
- Avoid words like Simple, Easy
- # 7 - Avoid Technical Jargon
- # 6 - Define ALL Acronyms
- # 5 - Avoid Memes/Colloquialisms
- # 4 - Use Meaningful Code Samples and Variable Names
- # 3 - Don’t Make Your Reader Leave Your Article
- # 2 - Make it Easy for the Reader to Find a Single Piece of Information
- # 1 - Verify Your Instructions! Test, Test, Test!
- # 0 Bonus! - Practice, Practice, Practice
- How You Can Get Started in Technical Writing (3 min)
- Conclusion & Questions (2 min)
none
Expected audience expertise: Python:none
Abstract as a tweet:Think of that feeling you get when you follow an online tutorial or documentation and the code works on the first run. But what makes one tutorial better than another? In this talk I'll discuss how you can write the documentation that developers love.
Mason is currently a Developer Advocate at Gretel. Prior to his work at Gretel, he was a Developer Advocate at DigitalOcean. Prior to this he was an SRE helping build and maintain a highly available hybrid multicloud PaaS. He is an avid programmer, speaker, educator, and writer. He is an organizer of PyTexas and actively contributes to open source projects. In his spare time he enjoys reading, camping, kayaking, and exploring new places.