Here's a report on Write the Docs 2014, Portland edition. Rather than just write up my notes from the talks I decided to write about selected interesting things. If you want to relive the talks, there are pictures, videos, and written notes online.
The conference is 2 days, with:
- a hike in the woods in which we got very wet (yay Spring in the Pacific North West)
- 2 full days of talks in the big room, including lightning talks
- a second track of talks in the small room after lunch
- impromptu small-scale discussion sessions in the smaller room after the talks there have finished
Tickets are cheap. So there are a lot of individual attendees and attendees from non-rich organizations, which helped give it an informal non-corporate feel. The main corporate influence seemed to be the many companies trying to hire technical writers. The ticket price also encourages a lot of local attendees: if you can spare 2 days, live in Portland, and have any interest in the subject, it's easy to justify a ticket.
It's inclusive, professionally speaking: there were writers and developers and sysadmins and managers and support people, and a lot of the talks were about the ways technical communication cuts across these different groups.
We talk a lot about the docs being "part of the product". But if they are, why don't we test them? And is the fact that we don't test them the reason they are so often so bad? One of the lightning talks was about testing the docs: give a 3rd party a job to do (write an add-on from scratch, for instance), and point them at the docs, to walk through what it's like for real new users. Real users file completely different bugs, they file bugs we didn't know about. Why don't we do this?
Is it possible to measure the effectiveness of docs? Another lightning talk discussed this. Can we measure how many people clicked all the way through a tutorial, and can we correlate that with people who created new repos? How many people who accessed the tutorial used that feature?
One of the great things about the conference was seeing how other people are approaching technical documentation. Sometimes in MDN I feel that we are too inward-looking, as if we've nothing to learn from others in the discipline. What other technologies have great documentation? What does it look like, and how is it produced? What can we learn from them?
The talk on "The Getting Stopped Experience: Improving Your Content’s First Impression " was interesting up to a point.
Google's documentation on getting started with their cloud platform was too hard to find, too long, and too difficult to follow. They introduced a metric called "Time To Hello World" (TTHW): time from wanting to start using the produce to having working "Hello World". By streamlining the process for new users they reduced this from hours to 15 minutes. So far so good. A lot of these changes are changes in the product, not the documentation. For example, one of the biggest initial hurdles for Add-on SDK users is the Python dependency, which the documentation can't remove.
Then they built a widget that lets users generate "Hello World" by pressing a button. TTHW is now 30 seconds. But this seems silly to me. A follow-along tutorial works by having the user do things: it's built on the assumption that this is how we learn. Removing some friction is a good thing, but removing all friction removes all its value.
So does a tutorial walk the line between frustration and mindless button-pushing? Or do we want to induce a little frustration: we learn by making mistakes and backtracking. So maybe we don't want new users to get so frustrated that they don't complete, but we want them to get just frustrated enough so they learn. Maybe we should introduce errors or omissions in tutorials.
One of my favourite talks used music as a metaphor for good documentation. Even when documents are complete and correct "without a theme, and harmony, and a pleasing tempo, you have a document that makes noise". We don't talk enough about this aspect of writing. Are the docs we write musical?
A big theme was the use of a model with Markdown-written docs being stored in GitHub repos and made into a website using readthedocs or something similar. Two talks were about this model: Kenneth Reitz on the Python Guide, and Patrick Arlt on using it as a Content Management System, and it came up in passing many more times.
There are many things this model gives, including:
- a collaboration mechanism through the ability to make, discuss, and revise pull requests
- allowing people to use their own editor of choice rather than forcing the WYSIWYG editor on them
- branching, so it's much easier to support different versions of the documentation to track different versions of a product
Another big theme was the importance of empathy. To write good docs, you need to understand your audience. Don't just assume you know who your audience is: ask them who they are, what they know, what they want. Put yourself in their place when you write. Ask other people to try your docs out. Use the APIs you document, use other, similar APIs and use their docs: note what works and what doesn't.
"to write the best teaching doc, you need to forget what it’s like to be an expert user of your tool"
These were my favourite talks (not counting Ali's talk obv. :).
-
Heidi Waterhouse — The New Sheriff in Town: Bringing Documentation Out of Chaos: getting started as a writer in an organization with no culture of documentation. Notes and video.
-
Matthew Lyon — Minimum Viable Documentation: the importance of empathy, helping new users, and documentation as part of the product. Notes and video.
-
Maxwell Hoffmann — Say more with less: writing for a global audience: crunchy detail on clear writing. Notes.
-
Christina Elmore — Death by Documentation: for anyone who gives presentations. Notes and video.
-
Christopher Kelleher — Make Music Not Noise: on the "musicality" of good documentation. Notes and video.
-
Zach Corleissen — More Than a Reference: Better APIs through Empathy: understanding the needs of your readers. Notes.
Books, websites, and so on, that looked interesting:
- Information Dashboard Design
- The Hitchhiker’s Guide to Python: collaboratively written book using GitHub+readthedocs
- "Madame Documentation": author of "What is Documentation?"
- An Introvert’s Guide to Better Presentations
Thanks for the write-up Will!