> Markdown version of [/videos/476-humanizing-your-documentation](https://www.wearedevelopers.com/videos/476-humanizing-your-documentation). Every page supports `.md` or `Accept: text/markdown`. Links point to the HTML versions so they work for humans too. Agent guide: [/agents.md](https://www.wearedevelopers.com/agents.md).

---

# Humanizing Your Documentation

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.

- **Speakers:** Carolyn Stransky
- **Event:** World Congress 2022
- **Published:** June 15, 2022
- **Duration:** 27:25
- **URL:** https://www.wearedevelopers.com/videos/476-humanizing-your-documentation

## Summary

Documentation often defaults to dry reference manuals that describe product features rather than addressing specific user needs. Shifting to use case-driven documentation—focusing on goals like "how to drill a hole" rather than "how to adjust drill speed"—transforms the reader's experience. By centering the human user, technical teams can design documentation concurrently with feature development, ensuring that guides actually help developers solve problems rather than contributing to the frustration that often drives them to the docs in the first place.

How technical content is written directly impacts a developer's sense of belonging and cognitive load. Removing isolating terms like "simply," "obviously," and "easy" sets a welcoming tone, as does replacing outdated, exclusionary terminology with semantic alternatives like allowlist and blocklist. Furthermore, while technical writing might seem a ripe place for humor, jokes rarely localize well and frequently annoy users who are already stuck on a technical roadblock. Utilizing tools like the Hemingway editor or inclusive language linters like AlexJS and write-good can help enforce plain phrasing and an accessible eighth-grade reading level. This combats the curse of knowledge, ensuring foundational concepts aren't skipped under the false assumption of a shared frame of reference. As technical writer Ashley Bishop notes, "no one has ever complained that something was too easy to read."

This empathy naturally extends into the explicit formatting of code snippets and troubleshooting tutorials. Code snippets must never be uploaded as screenshots; prioritizing semantic HTML tags and meaningful variable names over lazy placeholders like "foo" or "bar" ensures that examples are readable by assistive technology and easy to copy. Anticipating unexpected friction points is equally critical for adoption. Directly addressing common user syntax errors by detailing what happened, why it happened, and how to fix it establishes immediate trust. Ultimately, maintaining a comprehensive glossary and being completely transparent about product fit—explicitly telling a user when they might not need your tool—proves that a development community genuinely aims to be "honest, helpful, and human."

**Keywords:** use case-driven documentation, goal-oriented technical writing, developer documentation accessibility, inclusive technical language, writing plain language guides, eliminating isolating technical jargon, software documentation architecture, accessible code examples, structuring troubleshooting guides, formatting syntax error alerts, technical documentation glossary, semantic html for code snippets, descriptive variable naming, technical writing linters, documenting unexpected user errors

## Chapters

1. **Introduction to humanizing your technical documentation** (00:05) — Applying empathy and a user-focused narrative to external-facing documentation improves the learning experience for end users.
1. **Shifting focus to use case-driven documentation formatting** (01:49) — Focusing on user goals rather than just describing interface elements improves the utility of reference documentation.
1. **Applying goal-driven design principles to software examples** (03:49) — Showing exactly what a developer can accomplish with a tool directs them to the right reference endpoints.
1. **Designing documentation simultaneously with feature implementation phases** (05:45) — Starting documentation at the use case phase rather than after feature completion streamlines the writing process.
1. **Addressing user frustration and the reputation of developer documentation** (07:02) — Recognizing the emotional state of developers seeking help shapes a more supportive tone in technical writing.
1. **Fostering inclusion through deliberate word choice and sensitive terminology** (10:43) — Removing outdated and problematic acronyms ensures a more welcoming environment for diverse product users.
1. **Removing isolating words like simple and easy from guides** (13:04) — Replacing subjective descriptors with specific measurements or comparisons prevents reader alienation during unexpected troubleshooting tasks.
1. **Automating inclusive language checks with open source community linters** (15:00) — Automated command line linters help flag polarizing writing in markdown files but cannot fully replace human editing.
1. **Avoiding humor and unnecessary jokes in technical writing** (15:59) — Attempting comedy often frustrates users seeking quick task resolution and introduces unnecessary legal or localization challenges.
1. **Improving text readability with plain language validation tools** (16:57) — Processing complex prose through editing applications lowers readability scores for non-native speakers and neurodivergent readers.
1. **Documenting unexpected software errors and providing troubleshooting steps** (18:15) — Structuring error documentation to explain the cause and next actions reassures users when functionality fails.
1. **Overcoming the curse of knowledge through testing and glossaries** (19:38) — Testing tutorials aloud and explicitly defining project concepts bridges the missing context gap for true beginners.
1. **Formatting accessible code snippets and creating descriptive variable names** (21:26) — Writing explicit semantic markup and meaningful placeholders instead of screenshots improves the technical code learning journey.
1. **Structuring content hierarchies and explicitly stating specific product limitations** (24:12) — Disclosing inappropriate use cases immediately in the introduction builds trust and prevents wasted engineering hours.
1. **Adopting honest, helpful, and human technical documentation standards** (26:04) — Emphasizing accuracy alongside empathetic approachability builds a sustainable relationship with the developers using your product.

## Related Moments

- [Designing technical documentation for cross-functional audiences](https://www.wearedevelopers.com/videos/379-communicate-efficiently-with-software-architecture-diagrams) (from "Communicate efficiently with Software Architecture Diagrams")
- [Treating technical documentation as a core engineering practice](https://www.wearedevelopers.com/videos/727-the-abc-of-dx) (from "The ABC of DX")
- [Using goal-oriented documentation to create practical how-to guides](https://www.wearedevelopers.com/videos/798-continuous-documentation-for-your-code) (from "Continuous Documentation for Your Code")
- [Creating discoverable and accessible library documentation](https://www.wearedevelopers.com/videos/100345-code-once-use-everywhere-building-shared-libraries-for-multiple-projects) (from "Code Once, Use Everywhere: Building Shared Libraries for Multiple Projects")
- [Formatting documentation for fast developer scannability](https://www.wearedevelopers.com/videos/681-technical-documentation-how-can-i-write-them-better-and-why-should-i-care) (from "Technical Documentation - How Can I Write Them Better and Why Should I Care?")
- [Identifying common types of technical documentation](https://www.wearedevelopers.com/videos/681-technical-documentation-how-can-i-write-them-better-and-why-should-i-care) (from "Technical Documentation - How Can I Write Them Better and Why Should I Care?")

## Related Articles

- [Humanizing Your Documentation](https://www.wearedevelopers.com/magazine/133-humanizing-your-documentation)
- [The real reason we document our code](https://www.wearedevelopers.com/magazine/518-the-real-reason-we-document-our-code)
- [Technical Documentation For Developers](https://www.wearedevelopers.com/magazine/128-technical-documentation-for-developers)
- [7 Best Steps For Writing Good Software Technical Documentation](https://www.wearedevelopers.com/magazine/113-7-best-steps-for-writing-good-software-technical-documentation)

## Related Jobs

- [Senior Software Engineer](https://www.wearedevelopers.com/jobs/ext/15942-senior-software-engineer) at **GitHub**
- [Staff Software Engineer, Database Infrastructure](https://www.wearedevelopers.com/jobs/ext/1470125-staff-software-engineer-database-infrastructure) at **GitHub**
- [Manager, Technical Support](https://www.wearedevelopers.com/jobs/ext/737543-manager-technical-support) at **Twilio**
- [Principal Software Engineer, Database Infrastructure](https://www.wearedevelopers.com/jobs/ext/1465908-principal-software-engineer-database-infrastructure) at **GitHub**
- [Staff Developer Advocate, GitHub Security Lab](https://www.wearedevelopers.com/jobs/ext/1921051-staff-developer-advocate-github-security-lab) at **GitHub**
- [Senior Software Engineer, Client Apps Platform](https://www.wearedevelopers.com/jobs/ext/1773893-senior-software-engineer-client-apps-platform) at **GitHub**