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
28:19 MIN
How technical writing accelerates a developer's career
No more Node: Build APIs with Flask and test it with Postman
25:07 MIN
Final thoughts on audience-centric documentation and tools
Communicate efficiently with Software Architecture Diagrams
27:36 MIN
Fostering a team culture of writing and reading docs
Continuous Documentation for Your Code
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
20:25 MIN
Why documentation is essential for team collaboration
Continuous Documentation for Your Code
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
Featured Partners
Related Videos
31:23Technical Documentation - How Can I Write Them Better and Why Should I Care?
Hila Fish
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
22:45Documentation as a Tool: Introducing Documentation Driven Development
Abiodun Olowode
26:15Architecture Communication Canvas
Gernot Starke & Benjamin Wolf
28:22AI-Powered Code Documentation: Simplify the Complex
Patrick Schnell
28:11Communicate efficiently with Software Architecture Diagrams
Simon Lasselsberger
28:39It’s easy to create a good looking product, but what about a useful one?
Eleftheria Batsou
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.
Senior UX Writer
UserTesting
Documentation Expert
Anavia
Glarus Nord, Switzerland
Technical Documentation Editor
Acorn's Global Fleet
Steeton, United Kingdom
€30K
Adobe InDesign
Adobe Illustrator