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

@alispivak

• 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

@wiredferret

• 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

@starsseldomseen

• 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

@synthcat

• Meeting notes are like garbage trucks (user docs are like a red sports car).
• Sketch noting as meeting notes.
• Disregard chronology.
• Highlight the important stuff — make it red.
• WTF: Write the facts.
• Engage your SMEs.
• Make action items clear: Who, When, Where.
• Use collaborative tools (wiki, Docs, etc) — never email to distribute notes.
• Use Easter Eggs to combat tl;dr syndrome.
• HIPSTER IPSUM: http://hipsum.co/
• http://andrewspittle.com/2014/05/05/write-the-docs-mo-nishiyama-did-it-in-minutes-the-art-of-documenting-meeting-notes/

Nina Vyedin — Hacking the English Language

@misskallisto

• 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

@alex_gaynor

• 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

@topfunky

• Envisioning Information by Edward Tufte — got it.
• Information Dashboard Design by Stephen Few — got it.
• Use Type, Title & Subtitle, Color.
• Icons: Symbolset, Symbolicons
• Use explanatory symbolicons: Good/Bad, Problem/Solution, Before/After, Good/Better/Best, Analogy, Timelines.

Matthew Lyon — Minimum Viable Documentation

@mattly

• 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

@Beyond_YVR

• 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

@kennethreitz

• ReadTheDocs + GitHub = Python-Guide.org. It works really well: 156 active contributors. http://docs.python-guide.org/en/latest/

Maxwell Hoffmann — On Writing Concisely

@maxwellhoffmann

• 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

@ameliaabreu

• 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

@elchristina

• 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

@DrewAPicture

• 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

@susansls

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

James Pearson — Don’t Write Documentation

@xiongchiamiov

• 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

@cckelleher

• 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

@bltroutwine

• 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

@GrandmaHenri

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

Scot Marvin — Wabi-Sabi Writing

@scotmarvin

• 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

@brittagus

• 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

@jaredbhatti

• 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

@foxes96

• 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:
http://andrewspittle.com/tag/write-the-docs/