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.
Open Source Docs in Federal Gov't
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
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.
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'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.
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
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.
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
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.
What Writing Fiction Teaches You About Writing Documentation
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
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
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
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
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.
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!
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
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.
- 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.