Carolyn Stransky

Humanizing Your Documentation

Your documentation isn't for an ideal user; it's for a frustrated human. Here's how to write for them.

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.

Manual QA Engineer

Eltemate

Eltemate
Amsterdam, Netherlands

Intermediate
Senior
Test Planning
Manual Testing
+1

Matching moments

Making accessibility tooling actionable and encouraging
03:58 MIN

Making accessibility tooling actionable and encouraging

Developer Time Is Valuable - Use the Right Tools - Kilian Valkhof

The business case for sustainable high performance
03:34 MIN

The business case for sustainable high performance

Sustainable High Performance: Build It or Pay the Price

How AI threatens the open source documentation business model
08:29 MIN

How AI threatens the open source documentation business model

WeAreDevelopers LIVE – AI, Freelancing, Keeping Up with Tech and More

The value of progressive enhancement and semantic HTML
03:31 MIN

The value of progressive enhancement and semantic HTML

WeAreDevelopers LIVE – You Don’t Need JavaScript, Modern CSS and More

Empathizing with users over chasing engagement metrics
05:24 MIN

Empathizing with users over chasing engagement metrics

Slopquatting, API Keys, Fun with Fonts, Recruiters vs AI and more - The Best of LIVE 2025 - Part 2

Building trust through honest developer advocacy
02:48 MIN

Building trust through honest developer advocacy

Devs vs. Marketers, COBOL and Copilot, Make Live Coding Easy and more - The Best of LIVE 2025 - Part 3

Shifting from traditional CVs to skill-based talent management
05:17 MIN

Shifting from traditional CVs to skill-based talent management

From Data Keeper to Culture Shaper: The Evolution of HR Across Growth Stages

Automating formal processes risks losing informal human value
03:48 MIN

Automating formal processes risks losing informal human value

What 2025 Taught Us: A Year-End Special with Hung Lee

Featured Partners

Related Videos

See all videos
Technical Documentation - How Can I Write Them Better and Why Should I Care?31:23

Technical Documentation - How Can I Write Them Better and Why Should I Care?

Hila Fish

"I will remember that" and other lies - Why documentation matters and it makes your apps better25:25

"I will remember that" and other lies - Why documentation matters and it makes your apps better

Luise Freese

Continuous Documentation for Your Code20:19

Continuous Documentation for Your Code

Anastasiia Tymoshchuk

Architecture Communication Canvas26:15

Architecture Communication Canvas

Gernot Starke & Benjamin Wolf

AI-Powered Code Documentation: Simplify the Complex28:22

AI-Powered Code Documentation: Simplify the Complex

Patrick Schnell

Documentation as a Tool: Introducing Documentation Driven Development22:45

Documentation as a Tool: Introducing Documentation Driven Development

Abiodun Olowode

It’s easy to create a good looking product, but what about a useful one?28:39

It’s easy to create a good looking product, but what about a useful one?

Eleftheria Batsou

UX in the Dev Cycle: Moving from Handoff to Handshake26:13

UX in the Dev Cycle: Moving from Handoff to Handshake

Malte Breitzmann & Saskia Henatsch

Related Articles

View all articles
BB
Benedikt Bischof
Humanizing Your Documentation
About the speaker:Carolyn Stransky is a journalist, software engineer, conference speaker and technical writer based in Berlin. This is how she describes herself on her website:Majority of the week, I'm a frontend engineer focused on accessibility, d...
Humanizing Your Documentation
SM
Stephen McKenna
Technical Documentation For Developers
Technical documentation is an old strategy but essential in web development. However, it’s often a neglected part of the software development process. When done well, it can make a huge difference in the usability and quality of a product. But unfort...
Technical Documentation For Developers
DC
Daniel Cranney
The real reason we document our code
The world of software development moves fast. Technology is constantly changing, as are the tools we use with it, and even the role of a programmer is itself constantly in flux. However, some aspects of software engineering are so foundational that w...
The real reason we document our code

From learning to earning

Jobs that call for the skills explored in this talk.

Software Developer

Software Developer

Code Healers LLC
Hinesville, United States of America

Remote
€20-30K
Junior
Intermediate
React
JavaScript
TypeScript
+1
Software Developers

Software Developers

Code Healers LLC
Hinesville, United States of America

Remote
€30-40K
Intermediate
Senior
.NET
React
JavaScript
+2