Carolyn Stransky
Humanizing Your Documentation
#1about 4 minutes
Understanding use case-driven documentation for users
Focus documentation on user goals and what they can accomplish, not just on describing interface elements.
#2about 4 minutes
Shifting documentation earlier in the development lifecycle
Integrate documentation writing from the use case phase of development instead of treating it as an afterthought.
#3about 2 minutes
Choosing inclusive and neutral language in docs
Use precise, neutral, and inclusive language to create a welcoming environment and avoid problematic terms like master/slave or gendered pronouns.
#4about 3 minutes
Removing words like 'simply' and 'easy'
Replace patronizing words like 'simply' or 'easy' with specific, comparative, or absolute descriptions to avoid frustrating users.
#5about 2 minutes
Writing with plain language and avoiding humor
Avoid using humor which is hard to localize, and instead use plain language to make documentation more accessible and easier to read.
#6about 1 minute
How to document common errors effectively
Address common user errors by explaining what happened, why it happened, and what the user should do next to resolve it.
#7about 2 minutes
Overcoming the curse of knowledge in writing
Combat the curse of knowledge by explaining core concepts, avoiding assumptions, and providing a glossary for product-specific terms.
#8about 3 minutes
Writing clear and accessible code snippets
Improve code snippets by avoiding screenshots, using semantic HTML, enabling syntax highlighting, and replacing abstract placeholders with meaningful variable names.
#9about 2 minutes
Structuring docs and setting clear expectations
Maintain clear documentation by adopting a consistent structure and being transparent about your product's limitations and ideal use cases.
#10about 1 minute
Adopting honest, helpful, and human principles
Build trust and improve user experience by grounding your documentation in the core principles of being honest, helpful, and human.
Related jobs
Jobs that call for the skills explored in this talk.
Matching moments
01:32 MIN
Why great documentation is a cornerstone
Measuring Project Health in Open Source
Unlock full access
Log in or set up an account to access this feature and more.
05:34 MIN
How technical writing accelerates a developer's career
No more Node: Build APIs with Flask and test it with Postman
Unlock full access
Log in or set up an account to access this feature and more.
03:04 MIN
Final thoughts on audience-centric documentation and tools
Communicate efficiently with Software Architecture Diagrams
Unlock full access
Log in or set up an account to access this feature and more.
02:45 MIN
Fostering a team culture of writing and reading docs
Continuous Documentation for Your Code
Unlock full access
Log in or set up an account to access this feature and more.
01:43 MIN
Practical tips for making documentation a habit
"I will remember that" and other lies - Why documentation matters and it makes your apps better
Unlock full access
Log in or set up an account to access this feature and more.
01:53 MIN
Why documentation is essential for team collaboration
Continuous Documentation for Your Code
Unlock full access
Log in or set up an account to access this feature and more.
02:45 MIN
Why anyone can and should write technical documents
Technical Documentation - How Can I Write Them Better and Why Should I Care?
Unlock full access
Log in or set up an account to access this feature and more.
00:59 MIN
Understanding the developer paradox with documentation
"I will remember that" and other lies - Why documentation matters and it makes your apps better
Unlock full access
Log in or set up an account to access this feature and more.
Featured Partners
Related Videos
31:23Technical Documentation - How Can I Write Them Better and Why Should I Care?
Hila Fish
28:39It’s easy to create a good looking product, but what about a useful one?
Eleftheria Batsou
27:01UX is a fullstack job!
Marcel Bagemihl & Miriam Becker
29:59Racism fuels users experiences : why you should understand the strength of biased narratives.
Marcy Charollois
31:38Making Interactions Accessible to All Users
Anuradha Kumari
56:01Preventing Accessibility Issues Instead Of Fixing Them
Dirk Ginader
25:25"I will remember that" and other lies - Why documentation matters and it makes your apps better
Luise Freese
20:19Continuous Documentation for Your Code
Anastasiia Tymoshchuk
Related Articles
View all articles
.gif?w=240&auto=compress,format)
From learning to earning
Jobs that call for the skills explored in this talk.
TechBiz Global GmbH
Berlin, Germany
Remote
Docker
Node.js
Continuous Integration