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 · World Congress 2022

4:57 min

Treating technical documentation as a core engineering practice

Mike Elsmore · World Congress 2023

1:02 min

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

Anastasiia Tymoshchuk · World Congress 2023

1:14 min

Creating discoverable and accessible library documentation

Vadzim Prudnikau Vadzim Prudnikau · World Congress 2026 Europe

3:25 min

Building communication skills through technical writing roles

Teri Eyenike · LIVE

2:45 min

Formatting documentation for fast developer scannability

Hila Fish · World Congress 2023

More from World Congress 2022

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

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

André Kovac

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

The Design and Evolution of C++

Bjarne Stroustrup

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

But, you're not Facebook

Kristijan Ristovski

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

Communicate efficiently with Software Architecture Diagrams

Simon Lasselsberger

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

Get Ready for Jakarta EE 10!

Ivar Grimstad

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

Keep your code refactorable

Gerrit Stapper

Upcoming sessions on this topic

Open session

Teaching AI Coding Agents to Build It Right the First Time

  • Sajeetharan Sinnathurai

    Microsoft

    Principal Product Manager

Open session

Beware of Strangers Bearing Code: Open Source Trust in the Agent Era

  • Vikram Vaswani

    Consultant

Open session

Designing for Every Direction: Logical CSS for Global, Adaptive, and Effortlessly Reversible UIs

  • Vidhya Krishnamoorthy

    Morgan Stanley

    VP, Software Engineering Manager

Open session

How is SWE & EM roles are changing in the age of AI

  • Amol Sharma

    Stripe

    Engineering Manager

Open session

Prompt Debt: Why Your AI System Is Frozen in Time

  • Suriya Prakash B

    Red Hat

    Principal Software Engineer

Open session

From Prompt Engineering to Harness Engineering: Building Observable and Governed GenAI Systems

  • Lakshmi Devi Prakash

    JPMorgan Chase

    VP, Applied AI/ML Lead

Related videos

Technical Documentation - How Can I Write Them Better and Why Should I Care? thumbnail
31:23
World Congress 2023 • about 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
World Congress 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
World Congress 2026 Europe • 3 months ago

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

Edvin Teskeredzic

Diving into Developer Experience thumbnail
20:16
World Congress 2024 • about 2 years ago

Diving into Developer Experience

Ricky Holtz

Living Documentation That Can't Die thumbnail
19:16
Europe 2026 Virtual • 4 months ago

Living Documentation That Can't Die

Roman Liukevich

One Developer Journey, Two Surfaces thumbnail
29:13
Europe 2026 Virtual • 4 months ago

One Developer Journey, Two Surfaces

Saif Ali Shaik

Related articles

From learning to earning

Jobs that call for the skills explored in this talk.