Write The Docs: NA 2016


Another year of Write the Docs! Although I don't write as much documentation as I should, writing is such a key part of day-to-day human interaction, and WTD is always a good reminder of basic principles and encouragement to write more (docs). It's also an incredibly well run conference, done through trial and error. Every year they try new things, and keep the things that work. It's also one-track, which has pros and cons.

Pros: * Everyone has the same experience, and it's easy to discuss * You don't need to make any decisions or miss great talks

Cons: * You have to sit through some sub-optimal talks * Less walking and time between sessions

WTD is also held at the Crystal Ballroom in Portland, which is a great venue. It's friendly. It's not corporate-y. Good vibes all around. There were also talks. I wrote about them.

Side Note: There were many well-dressed humans, who had very well designed [clothes | bags | accessories]. It was wonderful to get out of the university fashion bubble.

Day 1

Open Source Docs in Federal Gov't

Britta Gustafson

Contributing to government software was a thought that had never crossed my mind, and it turns out that not all the governments software is horrible and outdated. In fact, they have a lot of really cool and interesting APIs, and are incredibly immersed in Open Source. Britta recently became a federal employee, working for the General Services Agency (GSA) on the 18F, and she gave a compelling talk on why contributing to the government helps you help others. We often think of the government as a crufty old gross thing that takes our money and makes bad decisions. But if we want that to change, we have the power, especially as software developers. Being part of that ecosystem can help strengthen a weak and imperfect system, and do good for a lot of people. All good things to think about, and really a core part of open source. Great talk, great speaker, great topic.

Customer Support + Docs

Neal Kaplan

This was a rough talk. It can really be summed up in one sentence: If you write docs, you should talk to your customers and customer support team more to get a feel for what customers need and what your docs are missing. A good point, but not a half-hour long point.

Documenting APIs

Allison Reinheimer Moore

Allison's talk was well put together and well-rehearsed, but without many memorable takeaways. APIs are so diverse that this is an understandably difficult talk to execute, and I recall it being unfortunately general.

Collaboration Between Open Source + Corporate Software

Shaun McCance

Shaun's talk was primarily a call to action for professional technical writers to help the open source projects they use write good documentation. Often community members are working on open source projects just for fun, and most developers don't find writing docs very fun. Understandably. So, as paid people who use words, if you're already writing docs for something, why not contribute that to open source? It strengthens both products, makes the world better, unicorns poop rainbows, yay. This was another talk that could really have been 5 minutes of "Hey, here's a thought you might not have had, do the things!", but it's a thesis I totally agree with.


Usually lunch doesn't get it's own section, but lunch at WTD was bomb. There was Caesar salad. Fresh veggies + fruit. And pasta with tomatoes, spinach, and hazelnuts. So good.

Lightning Talks

Dialog Trees

A talk on tool for making effective dialog trees for video games, specifically Yarn. Something I know nothing about, and very well done!


Static-site CMS? It's a thing. SSG with dynamic admin site. It seems pretty cool. Possible fodder for travel blog. Maybe best talk of the day in terms of content.

Cats: The perfect pets



I'm not even sure what this talk was about. It happened.

Copy That: Helping Users Succeed with Copy

Sarah Day

Documentation for people who don't read documentation! Product copy is the words you use in the product to guide users, like the label on a button, the title of a page, etc. It's definitely one of those things that I don't think about as often as I should, and was wonderfully specific and detailed. Sarah pulled up a page from GoodReads and talked about the use and misuse of copy on that page. There were diagrams, circles, and it was a very well-practiced and tight talk.

Readable README

Daniel Beck

More Zen

Tana Franko

A gentle reminder of a few often-heard principles that are easy to forget. Reframe how you think of problems. Simplify your work. Don't forget to have hobbies. This was a very successful and loosey-goosey 15 minute talk.

Embed the Docs

Kristof Von Tomme

Another 15 minute "Thunderstorm", this time on how important copy is. Less well done than the previous copy talk, but no less important a message.

Writing So Your Words Are Read

Tracy Osborn

Long and kind of interesting story? Not to disrespect Tracy, but stripping out the self-congratulation at the beginning and giving context in a slide or two would be much better. Her point of "Know your audience, they aren't necessarily you" is a good one, but again not worthy of a full half hour. She also makes a lot of assumptions about how technical people write, which are completely false in my experience. I'm definitely not the right audience for this talk, and as such didn't get much out of it.

Panel: Transforming Your Doc Process

The panel was probably fine? I don't know, I was really tired + over caffeinated and in desperate need of food.

Day 2

What Writing Fiction Teaches You About Writing Documentation

Thursday Bram

Thursday takes principles that everyone (even me -- really, everyone) has heard when writing fiction and talks about how you can apply it to writing documentation. It was more effective (for me personally) as a review of writing principles, but was a very entertaining and example-filled presentation none the less.

7 Values of Effective Tech Writing Teams

Joao Fernandes

Thesis: Help build products that need no documentation. In-app help, buttons | labels | tooltips, clear copy, etc. A few of the same ideas we've heard repeated at the conference: be brief, be concise, work with your team, know your audience & product & market, etc. But, if I had to choose one of the talks that covered these topics, it would be this one. The slides were gorgeous, and the speaker was relatively charismatic if a bit monotone. He also did an interesting thing where he would introduce an practice, then explain what would happen if you didn't adopt that practice, which seemed more effective & interesting than just saying to do the thing.

Building Documentation Culture in Startups

Ruthie BenDor

Talk of the day! Ruthie is an engineer with a range of experiences, and this was basically story time of good and bad experiences with docs. She's a great storyteller, really interesting tales with good morals & takeaways, and very funny. She also covered a 4-step guide to creating great internal docs that's general and applicable to any org. Super talk!

Following the Technical Doc Road

Christy Lutz

Very cute Wizard of Oz themed inspiration speech. Believe in yourself, work with your team, etc. Funny + well-executed + entertaining + ideal for 15 minute talk.

Using CSAT Data

Betsy Roseberg

CSAT == Customer Satisfaction. This was mostly about the value of having on-page user feedback + comment forms in your docs, and how to use that feedback productively. Excellent 15 minute talk.

Just-In-Time Documentation

Brianne Hillmer

The thesis: write your documentation when you know what problems your customers are having, don't try to guess what problems they will have in the future. This ends up being lots of short articles like "There's a gear button in the top left that looks little but actually takes you to what you want" that are only 2-3 paragraphs, but are exactly what people need. Overall very well executed, and especially able to keep the audience focused while smelling Burrito lunch!

Lightning Talks

Organizing Meetups

Definitely valuable if you're looking to start a meet-up, and the speaker seems like a very sweet if not well-spoken man.

Documentation in Academia

Given by my hilarious co-worker Jack, I'm 100% biased here. But like everything Jack does I thought it was clever, funny, and educational.

Earning User Trust


Interactive Document Environments

Tim Nugent & Paris Buttfield-Addison

Also a great talk! Interactive Documentation Environments are Code + Notes + Docs, and are a very pretty way of rendering and compiling together those three things into kind of actual docs.

Accessible Math on the Web

Tim Arnold

MathJax + MathML. If you haven't looked into them, you should!

Oops, I Became an Engineer

Tara Scherner de la Fuente

@goatuserstories is a funny twitter. Follow your dreams! Consider community college! Win + profit.

Main Takeaways

  • Consider working for the government. It won't get better by you being angry at it, and they actually do some very cool things.
  • What's the current state of your internal docs? It's so easy to focus on external docs, but your employees need docs too! A good litmus test is how long it takes a new hire to get their first PR up.
  • Look out for Lektor and Interactive Documentation Environments. The future is bright and beautiful
  • Remember your basic writing and humaning principles: know your audience; be brief; ask questions; have respect.