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
11:08 MIN
Why great documentation is a cornerstone
Measuring Project Health in Open Source
23:42 MIN
Practical tips for making documentation a habit
"I will remember that" and other lies - Why documentation matters and it makes your apps better
00:05 MIN
Why anyone can and should write technical documents
Technical Documentation - How Can I Write Them Better and Why Should I Care?
02:39 MIN
Understanding the developer paradox with documentation
"I will remember that" and other lies - Why documentation matters and it makes your apps better
19:01 MIN
How writing documentation improves your development skills
"I will remember that" and other lies - Why documentation matters and it makes your apps better
05:09 MIN
Exploring the essential types of product documentation
"I will remember that" and other lies - Why documentation matters and it makes your apps better
12:31 MIN
Tailoring content for internal and external audiences
Technical Documentation - How Can I Write Them Better and Why Should I Care?
08:19 MIN
Using documentation to advance your engineering career
Technical Documentation - How Can I Write Them Better and Why Should I Care?
Featured Partners
Related Videos
28:39It’s easy to create a good looking product, but what about a useful one?
Eleftheria Batsou
31:23Technical Documentation - How Can I Write Them Better and Why Should I Care?
Hila Fish
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
27:01UX is a fullstack job!
Marcel Bagemihl & Miriam Becker
31:38Making Interactions Accessible to All Users
Anuradha Kumari
29:59Racism fuels users experiences : why you should understand the strength of biased narratives.
Marcy Charollois
20:19Continuous Documentation for Your Code
Anastasiia Tymoshchuk
From learning to earning
Jobs that call for the skills explored in this talk.
Senior UX Writer
UserTesting
Barcelona, Spain
Front end Developer | Usability
Haystack People
Zwanenburg, Netherlands
React
Next.js
JavaScript
TypeScript
Product owner
Doccle-platform
Technical Software Documentation Officer
Guidant Global
Bristol, United Kingdom
€135K
Configuration Management
Technical Product Owner
CodeMinded
Amsterdam, Netherlands