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
25:07 MIN
Final thoughts on audience-centric documentation and tools
Communicate efficiently with Software Architecture Diagrams
28:19 MIN
How technical writing accelerates a developer's career
No more Node: Build APIs with Flask and test it with Postman
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:39It’s easy to create a good looking product, but what about a useful one?
Eleftheria Batsou
26:13UX in the Dev Cycle: Moving from Handoff to Handshake
Malte Breitzmann & Saskia Henatsch
Related Articles
View all articles
From learning to earning
Jobs that call for the skills explored in this talk.
User Documentation & Training Expert
European Dynamics
Brussels, Belgium
HTML
Confluence
Adobe Flash
Microsoft Office
UX Designer
DocuWare GmbH
Germering, Germany
Technical Product Owner
CodeMinded
Amsterdam, Netherlands
Technical Documentation Editor
Acorn's Global Fleet
Steeton with Eastburn, United Kingdom
€30K
Adobe InDesign
Adobe Illustrator
Technical Writer, Mechanical and Controls Documentation
Dematic
Banbury Civil Parish, United Kingdom
Remote
Senior
Scrum
Globalize Product Owner
Keywords Studios
Municipality of Madrid, Spain