WeAreDevelopers Logo WeAreDevelopers
Sign in
For You LIVE
World Congress 2022 • Jun 15, 2022

Humanizing Your Documentation

Carolyn Stransky

Stop writing dry reference manuals. Centering the human user in your documentation reduces cognitive load and builds trust. Learn to write clear, inclusive technical guides.

Pause
Mute Enter Fullscreen
#1 about 2 min

Introduction to humanizing your technical documentation

Applying empathy and a user-focused narrative to external-facing documentation improves the learning experience for end users.

#2 about 2 min

Shifting focus to use case-driven documentation formatting

Focusing on user goals rather than just describing interface elements improves the utility of reference documentation.

#3 about 2 min

Applying goal-driven design principles to software examples

Showing exactly what a developer can accomplish with a tool directs them to the right reference endpoints.

#4 about 2 min

Designing documentation simultaneously with feature implementation phases

Starting documentation at the use case phase rather than after feature completion streamlines the writing process.

#5 about 4 min

Addressing user frustration and the reputation of developer documentation

Recognizing the emotional state of developers seeking help shapes a more supportive tone in technical writing.

#6 about 3 min

Fostering inclusion through deliberate word choice and sensitive terminology

Removing outdated and problematic acronyms ensures a more welcoming environment for diverse product users.

#7 about 2 min

Removing isolating words like simple and easy from guides

Replacing subjective descriptors with specific measurements or comparisons prevents reader alienation during unexpected troubleshooting tasks.

#8 about 1 min

Automating inclusive language checks with open source community linters

Automated command line linters help flag polarizing writing in markdown files but cannot fully replace human editing.

#9 about 1 min

Avoiding humor and unnecessary jokes in technical writing

Attempting comedy often frustrates users seeking quick task resolution and introduces unnecessary legal or localization challenges.

#10 about 2 min

Improving text readability with plain language validation tools

Processing complex prose through editing applications lowers readability scores for non-native speakers and neurodivergent readers.

#11 about 2 min

Documenting unexpected software errors and providing troubleshooting steps

Structuring error documentation to explain the cause and next actions reassures users when functionality fails.

#12 about 2 min

Overcoming the curse of knowledge through testing and glossaries

Testing tutorials aloud and explicitly defining project concepts bridges the missing context gap for true beginners.

#13 about 3 min

Formatting accessible code snippets and creating descriptive variable names

Writing explicit semantic markup and meaningful placeholders instead of screenshots improves the technical code learning journey.

#14 about 2 min

Structuring content hierarchies and explicitly stating specific product limitations

Disclosing inappropriate use cases immediately in the introduction builds trust and prevents wasted engineering hours.

#15 about 2 min

Adopting honest, helpful, and human technical documentation standards

Emphasizing accuracy alongside empathetic approachability builds a sustainable relationship with the developers using your product.

Matching moments

1:58 min

Designing technical documentation for cross-functional audiences

Simon Lasselsberger · WWC 2022

4:57 min

Treating technical documentation as a core engineering practice

Mike Elsmore · WWC 2023

1:02 min

Using goal-oriented documentation to create practical how-to guides

Anastasiia Tymoshchuk · WWC 2023

1:14 min

Creating discoverable and accessible library documentation

Vadzim Prudnikau Vadzim Prudnikau · WWC Europe 2026

2:45 min

Formatting documentation for fast developer scannability

Hila Fish · WWC 2023

1:59 min

Identifying common types of technical documentation

Hila Fish · WWC 2023

More from World Congress 2022

What the heck do "declarative" and "reactive" actually mean? thumbnail
30:40
almost 4 years ago

What the heck do "declarative" and "reactive" actually mean?

André Kovac

The Design and Evolution of C++ thumbnail
1:01:15
about 4 years ago

The Design and Evolution of C++

Bjarne Stroustrup

But, you're not Facebook thumbnail
31:12
about 4 years ago

But, you're not Facebook

Kristijan Ristovski

Communicate efficiently with Software Architecture Diagrams thumbnail
28:11
about 4 years ago

Communicate efficiently with Software Architecture Diagrams

Simon Lasselsberger

Get Ready for Jakarta EE 10! thumbnail
42:53
about 4 years ago

Get Ready for Jakarta EE 10!

Ivar Grimstad

Keep your code refactorable thumbnail
26:46
about 4 years ago

Keep your code refactorable

Gerrit Stapper

Upcoming sessions on this topic

Open session

World Congress 2026 North America

When Humans Stop Writing Code: Rethinking Languages, Compilers, and Responsibility

Simon Auer

Organizer of flutter vienna meetup and CEO of marqably

Simon Auer
Open session

World Congress 2026 North America

The spectrum of agentic coding: From vibe coding to high-quality software engineering

YK Sugi

Developer Experience Manager at Eventual

YK Sugi
Open session

World Congress 2026 North America

Vibe Coding Accessibility

Karl Groves

Focused on actively fixing accessibility

Karl Groves
Open session

World Congress 2026 North America

Beyond Vibe Coding: Using CLI Tools as Your AI Counterpart in Pair Programming

Ron Veen

Java enthusiast and Special agent for Team Rockstars IT

Ron Veen
Open session

World Congress 2026 North America

Secure-by-Inclusion: Preventing Accessibility Barriers from Becoming Security Vulnerabilities

Radostina (Ina) Tsvetkova

Norwegian Directorate of Labour and Welfare (NAV), Senior Advisor in Digital Accessibility and Inclusive Design

Radostina (Ina) Tsvetkova
Open session

World Congress 2026 North America

AI-Driven API Design

Mike Amundsen

Author, Adviser, Trainer

Mike Amundsen

Related videos

Technical Documentation - How Can I Write Them Better and Why Should I Care? thumbnail
31:23
WWC 2023 • almost 3 years ago

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

Hila Fish

Continuous Documentation for Your Code thumbnail
20:19
WWC 2023 • almost 3 years ago

Continuous Documentation for Your Code

Anastasiia Tymoshchuk

Making Documentation AI-Ready: Preparing Your Docs for the LLM Era thumbnail
27:16
WWC Europe 2026 • about 1 month ago

Making Documentation AI-Ready: Preparing Your Docs for the LLM Era

Edvin Teskeredzic

Diving into Developer Experience thumbnail
20:16
WWC 2024 • almost 2 years ago

Diving into Developer Experience

Ricky Holtz

One Developer Journey, Two Surfaces thumbnail
29:13
Europe 2026 Virtual • about 1 month ago

One Developer Journey, Two Surfaces

Saif Ali Shaik

Developer Tested, Educator Approved thumbnail
21:52
WWC 2024 • almost 2 years ago

Developer Tested, Educator Approved

Andrew MacLean, MetzinAround

Related articles

From learning to earning

Jobs that call for the skills explored in this talk.