Write The Docs

Conference Notes

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: