#PyConUS2022 @masonegger on Write Docs Devs Love. Ten Tricks to Level Up Your Tech Writing
Follow along and get the slides by scanning the barcode:
Follow along and get the slides by scanning the barcode:
#PyConUS2022 @masonegger
What is tech writing?
TFW when you follow an online tutorial or docs and the code works on the first run.
Then think of the hours spent wasted following outdated docs.
The difference is Tech writing.
What is tech writing?
TFW when you follow an online tutorial or docs and the code works on the first run.
Then think of the hours spent wasted following outdated docs.
The difference is Tech writing.
#PyConUS2022 @masonegger
Tech writing is important because it's the FIRST impression of your project. It's the first level marketing.
If user don't like your docs, they leave and find another tool.
Tech writing is important because it's the FIRST impression of your project. It's the first level marketing.
If user don't like your docs, they leave and find another tool.
#PyConUS2022 @masonegger
Tech writing is to teach users how to use your project effectively and safely. Docs helps build a community around your project.
Tech writing is to teach users how to use your project effectively and safely. Docs helps build a community around your project.
#PyConUS2022 @masonegger
Tip #10: Have a clear concise goal in your doc in the first paragraph
Make it obvious what your reader will have learned/built in the end after reading the doc
Tip #10: Have a clear concise goal in your doc in the first paragraph
Make it obvious what your reader will have learned/built in the end after reading the doc
#PyConUS2022 @masonegger
Tip #9: Don't be overly verbose.
Docs should be concise, not a novel
Always assume readers don't speak the same language as you.
Aim for a low reading level. (i.e grade 3 reading level) It will help the non-native speaking reader.
Tip #9: Don't be overly verbose.
Docs should be concise, not a novel
Always assume readers don't speak the same language as you.
Aim for a low reading level. (i.e grade 3 reading level) It will help the non-native speaking reader.
#PyConUS2022 @masonegger
Tip #8 Use inclusive language.
Avoid gendered language and go for more gender neutral pronouns.
Avoid using known slangs that are derogatory.
i.e don't use noobs, 10x devs, dummies.
Avoid words that make someone doubt their own skills.
Tip #8 Use inclusive language.
Avoid gendered language and go for more gender neutral pronouns.
Avoid using known slangs that are derogatory.
i.e don't use noobs, 10x devs, dummies.
Avoid words that make someone doubt their own skills.
#PyConUS2022 @masonegger
Tip #7 Limit Technical Jargon
Overusing jargon makes it difficult for beginners.
Know your audience to decide how much jargon.
Tip #7 Limit Technical Jargon
Overusing jargon makes it difficult for beginners.
Know your audience to decide how much jargon.
#PyConUS2022 @masonegger
Tip #6 Define ALL acronyms
Some acronyms have two or three different meanings.
They scare and intimidate readers, especially new learners
Tip #6 Define ALL acronyms
Some acronyms have two or three different meanings.
They scare and intimidate readers, especially new learners
#PyConUS2022 @masonegger
Tip #5 Avoid memes/idioms and regional language (unless you're positive of who your audience is)
Tip #5 Avoid memes/idioms and regional language (unless you're positive of who your audience is)
#PyConUS2022 @masonegger
Tip #4 Use meaningful code samples and variable names
Don't tell people what problem your code solves. Show them.
Use meaning variable names. Foo and bar are useless. They need to go! 👏🏻
Have completed copy of code for copy/paste
Tip #4 Use meaningful code samples and variable names
Don't tell people what problem your code solves. Show them.
Use meaning variable names. Foo and bar are useless. They need to go! 👏🏻
Have completed copy of code for copy/paste
#PyConUS2022 @masonegger
Tip #3 Avoid making your reader leave your Docs
Avoid sending reader to many other sites
(or they may not come back)
So give them a way to come back to your doc.
Provide links at the beginning, have a list of prerequisites to be completed beforehand.
Tip #3 Avoid making your reader leave your Docs
Avoid sending reader to many other sites
(or they may not come back)
So give them a way to come back to your doc.
Provide links at the beginning, have a list of prerequisites to be completed beforehand.
#PyConUS2022 @masonegger
Tip #2 Make your content scannable
Beginners tend to read the entire posts, while experienced users will scan for the content. they need.
Use headings and subheadings. Use Table of Contents.
Tip #2 Make your content scannable
Beginners tend to read the entire posts, while experienced users will scan for the content. they need.
Use headings and subheadings. Use Table of Contents.
#PyConUS2022 @masonegger
Tip #1 Verify your instructions! Test, test and test!
The only thing worst than no docs, is incorrect docs.
Have someone else test your work. Get people involved.
Tip #1 Verify your instructions! Test, test and test!
The only thing worst than no docs, is incorrect docs.
Have someone else test your work. Get people involved.
#PyConUS2022 @masonegger
Bonus tip! Practise!
The best way to get better at tech writing is to write!
Just write. You don't always have to publish it.
But don't throw it away! Save it for future you.
Bonus tip! Practise!
The best way to get better at tech writing is to write!
Just write. You don't always have to publish it.
But don't throw it away! Save it for future you.
#PyConUS2022 @masonegger
How to get started in tech writing:
Write docs at work! Your manager will love you! 👏🏻
Start a blog
Contribute to open source projects. OS projects always need help with docs! 👏🏻 YES!!
How to get started in tech writing:
Write docs at work! Your manager will love you! 👏🏻
Start a blog
Contribute to open source projects. OS projects always need help with docs! 👏🏻 YES!!
• • •
Missing some Tweet in this thread? You can try to
force a refresh
