Write the Docs 2017
2017-05-14..2017-05-16
San Francisco, CA, United States
who it's for
technical writers, documentation managers, support engineers, site reliability engineers, devops engineers, community managers
topics
error message design; documentation navigation patterns; documentation as care; design critique practices; documentation sprint workflows; automated doc testing; runbook and incident docs; naming and terminology refactoring; docs-as-code CI workflows; crowdsourced documentation contributions; bootstrapping docs at startups
| title | author | length |
|---|---|---|
| Introduction & State of the Docs | Eric Holscher | 23m |
State of the Docs gives numbers and experiments: 1800 people in Slack, eight newsletters, five podcast episodes, a writing day with about 100 contributors and… | ||
| Error Messages: Being Humble, Human, and Helpful will make users Happy | Kate Voss | 16m |
Distills error types into user errors vs system errors, then prescribes three concrete rules — be humble, be human, be helpful — with examples: Netflix… | ||
| Building navigation for your doc site: 5 best practices | Tom Johnson | 21m |
Usability testing shows users routinely fail to locate answers so five concrete practices guide fixes: use the doc homepage as a routing portal, add a… | ||
| Caring Systems: Documentation as care | Amelia Abreu | 21m |
Argues documentation is documentation as informational care with three care types—instrumental, emotional, informational—and cites consultancy case studies… | ||
| You have Already Succeeded: Design Critique Guidelines make Feedback Easier | Christy Lutz | 21m |
Claim: asking for feedback already counts as success and a short set of design critique guidelines makes critique actionable. Steps: write a scope/skill… | ||
| No Community Members Were Harmed in the Making of This Doc Sprint: How we ran a 48-hour Event to Collect Community Wisdom into a Guidebook for Newsroom Developers | Lindsay Muscato, Ryan Pitts | 26m |
A 48-hour documentation sprint gathers 11 in-person contributors and about a dozen remote editors to produce an eight-chapter Field Guide to Open Source in the… | ||
| Testing: it's not just for code anymore | Lyzi Diamond | 25m |
Mapbox builds an automated content testing system using docbox and retext-mapbox-standard to enforce structure, language, and examples; tests fail builds when… | ||
| Do you Know a Runbook From a Flip Book?... | Andrea Longo | 28m |
Survey of what ops teams actually keep and use: runbooks with step‑by‑step failover and malware‑cleanup procedures, cookbooks and tutorials for config and… | ||
| Even Naming This Talk Is Hard | Ruthie BenDor | 26m |
Argues that naming is the core problem not the topic and gives concrete failures and fixes: builds a mental to‑do app as a running example, finds naming… | ||
| Only Interesting Conversations: The Symbiotic Relationship Between Docs and Support | Matthew Buttler | 21m |
Argues that direct partnership with support reduces repeated, boring tickets by building targeted how‑tos: created a domain configuration playbook with… | ||
| Everyone's a player (in a mid-90s MUD) | Kenzie Woodbridge | 30m |
Claim: applying Player Type Theory to documentation increases contributions by matching strategies to motivations. Practical tools include templates and… | ||
| Treating Documentation like Code: a Practical Account | Jodie Putrino | 23m |
Project puts docs in the code repo and uses Sphinx (Python projects) with Read the Docs early then moves builds to AWS S3 for security. CI runs in a Docker… | ||
| Interviewing and hiring technical writers: the Siberian way | Sam Faktorovich | 25m |
Claim: hire excellent writers and train them on technical fundamentals rather than teaching coders to write. Process uses a lengthy pre-interview test: explain… | ||
| The Wisdom of Crowds: Crowdsourcing Minimalism in an Open Organization | Ingrid K Towey | 33m |
Claim: crowdsourcing drives a shift to minimalist, customer‑focused docs. Method: run regular crowdsourced minimalist critiques using a clear checklist of five… | ||
| Start with the tasks, not the endpoints | Sarah Hersh | 28m |
NPR One Developer Center redesign starts from interviews with partner developers to map real tasks (playing audio, posting ratings, auth flows), then… | ||
| Bootstrapping Docs at a Startup | Jesse Seldess | 29m |
Bootstrapping docs at a startup is a concrete playbook: documentation for CockroachDB gets built from scratch by the first tech writer while the product has… | ||
| Lightning Talks Part 1 | Jed Hartman, Mike Jang, Joe Lodin, Paul Anzel, Troy Howard | 25m |
Six lightning pieces make specific, actionable claims: a Google developer docs style guide public release and why a written guide saves decisions and enforces… | ||
| Lightning Talks Part 2 | David Ryan, Ryan Macklin, John Mulhausen, Rich Marcucella, Marya Devoto, Dan Stevens | 25m |
Crowdsourced “top 10” myths get tested with concrete claims and counterexamples, a docs‑as‑code push and the assertion that nobody reads documentation is… | ||
| Lightning Talks Part 3 | Brian Dominick, Dante Blando, Mary Ellen Niedzielski, Cynthia Ng, Ashleigh R., Rose Williams, Mikey Ariel | 32m |
A collection of six rapid reports shows useful specifics: a Ruby tool called liquid_achatz single‑sources YAML data and templates to produce Asciidoc HTML JSON… | ||
| nothing matches | ||