WriteTheDocs Conference Rundown

Earlier this week, I attended and gave a talk (Motivating Developers to write API Documentation -- based on my experiences with the Drupal project) at the first WriteTheDocs conference in Portland, Oregon. The conference overall was pretty good:

• Good program (the speaker and topic selection was excellent)
• Good food
• Free drinks
• The WiFi worked (not always the case at conferences)
• Lots of side activities (hike, pre-conference meet-and-greet, parties and gatherings)
• Portland is a great city

The only thing I thought was not so great was the venue -- which was a neat old building but in my opinion not the best place for a conference:

• Non-ADA accessible (perhaps someone in a wheelchair could have gotten in, but they definitely would not have been able to reach the bathrooms)
• No "hang-space" -- no one is going to be interested in every talk (and I definitely didn't want to sit through two whole days of talks even if they were mostly of interest -- brain melt!), but there was no place to be except in the main theater space.
• Not enough tables (pretty much everyone had a laptop or paper for notes)
• Poor lighting (theater-style lighting meant the speakers could not see the audience, making it less interactive, and upstairs you would have needed back-lit paper to take notes)

A few take-home messages from the first day's talks (hopefully the speaker slides and videos will be posted on the conference site soon):

• Kenneth Reitz... To write a good API: Write the README file first, then the docs, then the API itself.
• Michael Verdi... The Mozilla project has some interesting work-flow around their support wiki in regards to translations and revisions: Keep track of "helpfulness" ratings and aim to revise the least helpful docs. When making revisions, have a way to mark them as needing translation update or not. A side-by-side editor for making translations, which highlights changes since the last translation update. A way to find the most popular docs to concentrate on getting them translated first. A policy of minimizing revisions on those docs so as to minimize the need for translation updates.
• Matthew Butterick... Typogography (font size, line length, etc.) is really important for readability. Use colors etc. to emphasize things that are actually important, and be careful not to use colors that would make unimportant things stand out.
• Lightning talk (not sure who, sorry!)... Keep track of failed searches for documentation and use them to know what documentation needs to be written or what keywords need to be added to existing documentation.
• Kevin Hale... Make everyone in the company/group do support from time to time, so they really understand what users go through.
• Nisha George and Elaine Tsai... The Support team can/should own some documentation.
• Brandon Phillips... Set up documentation so you don't have to click through so many layers of navigation -- single-page documentation. But Kevin Hale commented that for novice users, this style of documentation is overwhelming according to his usabilty testing.

I ended up leaving after the first day due to my brain being overloaded and a lot of work to do, but I just wanted to say thank you to the organizers, speakers, and sponsors!