Write The Docs

Conference Notes

Marko Gargenta
May 6, 2014 · 8 min read

Photo by @ruthlovescake

The following are my notes from Write The Docs conference in Portland in May 5&6, 2014. I covered most, but not all talks.

Ali Spivak — Communities are Awesome


  • Mozilla Developer Network is responsible for all Mozilla docs.
  • Mozilla does Doc Springs — ½ day to a day events to focus on docs.
  • Make is super easy for people to contribute!
  • Trust your users to make changes.
  • What motivates the community:
  • Extrinsic (mostly weak)
  • Money (terrible)
  • Badges
  • Fear of failure
  • etc.
  • Intrinsic (much better!!!)
  • Be part of something bigger.
  • Contribute expertise to much bigger audience.
  • Autonomy/Mastery/Purpose
  • Burning Man as the community
  • Participation: everyone welcome, everyone participates.
  • Transparent: to build trust?
  • Zappos: doesn’t matter what principles are, it matters that you have them #CULTure

Heidi Waterhouse — New Sheriff in Town: Bringing documentation out of chaos


  • I’m Better and cheaper than your developers.
  • All docs are equivalent to code, so should be treated as code.
  • Use bug tracking for documentation.
  • Know your users: different docs for different audience.
  • Deputize vigilantes!
  • Build infrastructure: templates, structure.
  • Be sure docs are seen as integral part of the product: go to team meetings, etc.
  • Plats for docs: Use, Configure, Customize, Fix, Reference — basically classes of docs.

Amalia Hawkins — Ignorance Is Strength: Writing Documentation By Learning As You Go


  • Best TAs are the Bs and Cs, the ones who struggled with the material, not the A-students.
  • Figuring out 1.4 MLOC — Code will give you what and how, but not the why (the context).
  • Not having docs -> talking to engineers to get the context doesn’t scale.
  • Writing anything, even if it’s wrong, as first draft is better than having nothing — others will start improving it.
  • Ignorance is strength.

Mo Nishiyama — Did It In Minutes: The Art of Documenting Meeting Notes


Nina Vyedin — Hacking the English Language


  • Under pressure — the worst place to be is at staring at the empty doc.
  • Don’t start with a blank page — start with the Hello, Doc!
  • Documentation Spec: Questions to ask to understand the project.
  • Docs Design Patterns
  • Start with the Architecture, then create the outline.
  • Error/Avoid/Use Instead patterns.
  • Edit for structure and flow, not just for English.
  • Editing: prove structure, improve reliability and reduce complexity without changing the its purpose.
  • Don’t just edit, refactor!
  • Peer edits

Alex Gaynor — Documenting Domain Specific Knowledge


  • Created Django — strong culture of documentation,
  • Tutorials for new users.
  • Know your users.
  • Know your domain — for Django it’s web so assume they know that already.
  • Focus on your users in known domain.
  • Domain: user new to your subject but expert with everything else.
  • Straight line docs (optional stuff can be a link).
  • Don’t use jargon.
  • Enable use cases.
  • Composition is great (smaller pieces — divide and concur) but make sure you connect the dots for the user.
  • Get someone to test your docs.
  • Give users early wins.

Geoffrey Grosenbach — Graphical Explanations


Matthew Lyon — Minimum Viable Documentation


  • Build as little as possible.
  • Minimal cross Viable, there’s a very small Feasible intersection.
  • Minimal Viable Docs: empathy is the key. Get in the head of the users — not a skill of most engineers.
  • Dungeons & Dragons: a useful role-playing tool.
  • HOWTOs are the biggest bang for the buck. From zero to hero.
  • UX debt — use HOWTOs to keep a handle on it.

Lois Patterson — What Makes Good API Documentation: An Example-Based Approach


  • Twitter APIs are one of the best. Others are Netflix, Flickr, Facebook, PayPal, etc.
  • Swagger and Atlassian allow you to test REST API right in the browser.
  • Version your docs, use same version number as the API.
  • Test environments are useful.

Kenneth Reitz — Documentation at Scale


Maxwell Hoffmann — On Writing Concisely


  • ASD-STE 100 Simplified English makes your docs 30% smaller.
  • Don’t use passive voice — hard to translate.
  • One topic per sentence.
  • Use valid nomenclature.
  • Write simple sentences.
  • Use active voices — millennials use them (they’re reincarnated people from the 60s).
  • Don’t use gerunds (“ing”).

Amelia Abreu — Data, Documentation and Memory


  • In 1950s, French had the Madame Documentarian as well as Documentation Syndicate.
  • Amazon sold books at cost to gather customer data, so they could sell them everything else.

Christina Elmore — Death by Documentation


  • Documentation vs. Presentation: when should we be doing one, the other, or both.
  • Documentation:
  • Self-guided
  • Meant to read
  • Presentation:
  • Presenter-guided
  • Meant to be heard
  • Good presentation slides are bad documents.
  • When we don’t get the difference between docs and slides, both suffer.
  • At Amazon and Linkedin: first 10 minutes of the meeting, everyone reads the doc relevant for the meeting, then the rest is discussion about the topic.
  • Slidedocs: http://www.duarte.com/slidedocs/ a good experiment/tool.
  • Nurture a Culture of Documentation.
  • DocDay as DocsRocks or Doc Sprint.

Drew Jaynes — Putting the (docs) Cart Before the (standards) Horse


  • The Codex: manually curated wiki with 2300+ pages. Became unsustainable.
  • Developed inline documentation standard.
  • Never underestimate the power of the docs team with a documentation roadmap.
  • The Codex will become a giant redirect from wiki to inline docs.
  • If you’ve got no documentation, it’s a bug.
  • Docs are part of core coding standards. It’s the Definition of Done.

Susan Salituro — From docs to engineering and back again


  • Math + English: left/right part of the brain.
  • The marriage of UI design and technical writing.

James Pearson — Don’t Write Documentation


  • The worst enemy of good docs are bad docs.
  • People generally think documentation is bad and don’t read it.
  • The broken window syndrome definitely true with docs and software.
  • code + docs + tests + metrics + alerts
  • The great virtues of programmers.
  • JavaDoc is a great tool gone bad.
  • Omit useless words.
  • Multi-level verbosity (like ssh -v).
  • Poka-yoke: http://en.wikipedia.org/wiki/Poka-yoke
  • Fix product failures instead of documenting around it.

Christopher Kelleher — Make Music Not Noise


  • Docs as music, or noise.
  • Reading a page takes 90 seconds; T&C can be 30 pages => ~45 minutes or reading.
  • The biggest lie: “I have read and agree to all the terms”.
  • Intentional noise: T&C to get you to click Yes.
  • Lousy docs increase authority.
  • Python docs are well done.

Brian L. Troutwine — Instrumentation as Living Documentation: Teaching Humans About Complex Systems


  • 55 billion transaction per day.
  • <100ms latency.
  • Key challenge of sustaining complex system is maintaining our understanding of it.
  • So, we document them.
  • Complex systems are difficult to communicate about.
  • Hard to see complex systems with the Beginner’s Eye.
  • Documentation reduces accidents — it doesn’t solve them.
  • Engineers fail to update the docs as they update the system.
  • Normal Accident: every system has some failure built to it: http://www.amazon.com/Normal-Accidents-Living-High-Risk-Technologies/dp/0691004129
  • Instrumentation as a process to manage Normal Accidents.
  • Flip side of instrumentation is sense of big brother watching.
  • Instrumentation is like a suit. Everyone should have a dashboard that fits their own mind.
  • Instrumentation helps documentation, and documentation helps instrumentation. Complex systems need both.
  • DataDog, NewRelic

Lauren Rother — We Strongly Recommend You Write Best Practices


  • Easy table of contents.
  • Short code snippets are worth many words.
  • Snazzy diagrams break the monotony of text.

Scot Marvin — Wabi-Sabi Writing


  • Wabi-Sabi tenants: beauty in imperfection/incompletion/impermanent.
  • Wabi-Sabi aesthetic: rustic, simple, clean, asymmetrical, tranquil.
  • Excellence vs. perfection.
  • Salad bar Agile — everyone picks what they want.
  • Agile: just incremental better.
  • People don’t want to read — they want to browse.
  • Write like Hemingway — use short sentences. Try http://www.hemingwayapp.com/
  • The goal is to put support out of business.
  • Less Versailles more Ryoan-ji — or a don’t-get-to-cute principle.
  • “Done is beautiful”

Britta Gustafson — Strategies to fight documentation inertia


  • Ask beginners to write things down as they learn.
  • Documentation as a marketing problem.
  • Make docs fun by copyediting new stuff (shows someone cares).
  • Make the wiki look good — be attractive.
  • Thank your contributors. Be specific. Right away. Publicly.
  • Give users permission to contribute.
  • Wiki social engineering: leave imperfections for others to contribute to.
  • Write bad first drafts as motivation.

Jared Bhatti — The Getting Stopped Experience: Improving Your Content’s First Impression


  • Every Google Cloud product has its own Getting Started experience, but they all combine into their own sets of Getting Started experiences as well.
  • What are some of your challenges for getting users started on your product?
  • Google problems:
  • Findability
  • Complexity and density
  • Poor connection with the users
  • Getting Started:
  • 1. Find helpful content.
  • 2. Get something working.
  • 3. Get your thing working.
  • 1. Finding helpful content.
  • Try to search for your own product.
  • See how your competitors are doing it (especially the small ones).
  • 2. Get something working: user research to improve Getting Started UX. Create Hello, World!
  • User is always in control.
  • Give users what they want quickly.
  • Reduce friction everywhere.
  • Show, don’t tell.
  • Measure TTHW: Time To Hello World.
  • Dogfood your product.
  • Log friction.
  • Measure and reduce TTHW
  • 3. Get your thing working.
  • Bring in your users. (Stackoverflow)
  • How are you interacting with your larger community?

Zach Corleissen — More Than a Reference: Better APIs through Empathy

  • Empathy: capacity to recognize emotions of your users.
  • Empathically, you need to be your own user.
  • Write for your readers.
  • What users what the most: written instructions (HOWTOs) and sample code.
  • Why does this API matters?
  • Provide friendly UI: single page docs, better typography (ditch Arial).
  • Engage empathy of allies: support team, Stackoverflow, communities.
  • Explain how to get started.
  • Give most attention to most commonly used endpoints.
  • Lavishly document edge cases and failure states — what to do when things go wrong.
  • Provide meaningful error messages — e.g. not generic HTTP 404s and 500s.
  • Twillio as example of good API: http://www.twilio.com/docs/api/rest
  • Google AdWords is an example of bad API: https://developers.google.com/adwords/api/
  • Lucene is the example of ugly API: http://lucene.apache.org/core/4_8_0/index.html
  • Increase your empathy by forgetting everything you know and putting yourself in your users’ shoes.

Patrick Arlt — Ditch your CMS with Git and Static Site Generators

@patrickarlt, slides: http://patrickarlt.github.io/ditch-your-cms-talk/#/

  • 1,000s of pages in CMS that nobody wanted to use.
  • Wanted to create docs the same way they build their website.
  • Get developers to apply the same tools they already know and love to documentation as well.
  • Docs as source code from which a tool builds HTML — flexible and nice system for managing large sets of documents.
  • Markdown is super simple, and very extensible.
  • Git: versioning, workflow, collaboration
  • GitHub: issues, wikis, pull requests
  • Git may be complicated at first but it’s better than any other CMS tool you might have ever used before.
  • Git makes developers happy, but not necessarily writers.
  • Markdown + Git = Flexible and Scalable Documentation

Mark Tattersall — Documentation as a Product


  • Documentation IS a product.
  • Docs thinking -> tactical.
  • Holistic approach to product.
  • Complex documentation: multiple supported platforms, versions, etc.
  • Writing the docs well in advance of having the product released.
  • What problems are the docs solving?
  • Open source projects are nodes in an ecosystem — docs are important to understand how each fits within the system.
  • Docs are for both existing AND potential users.
  • Docs as Marketing.
  • Docs as a Guide.
  • Use NPS to measure sentiment.
  • What are the success factors for moving the needle for company goals?
  • Experience vs. Knowledge

Other notes from the conference:

Notes from UX/Content Strategy/Content Marketing Conferences

A curated collections of notes from top conferences for UX professionals, content strategists, social media and digital marketers.

Marko Gargenta

Written by

Editor of PlusPlus Ideas. Curious about how people get to the next level.

Notes from UX/Content Strategy/Content Marketing Conferences

A curated collections of notes from top conferences for UX professionals, content strategists, social media and digital marketers.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade