Write the Docs: Portland, Oregon, April 8–9

Amy Brown

This week I went to the first-ever Write the Docs conference. Write the Docs, as I understand it, intends to create a community of the people who write documentation for open source projects. There are plenty of professional groups for technical writers, and plenty of communities online and off for open source developers, but open source documentarians (a made-up word) exist in an awkward nether-world, neither corporate and well-trained like professional tech writers nor, well, reluctant to write documentation like open source developers.

That awkward nether-world was embodied in Portland last Monday and Tuesday. The geniuses who put the conference together booked an old theatre, gathered a diverse group of speakers of various levels of seasonedness (another made-up word), sold 220 tickets to a yet-more diverse* group of people and put us all together in a room for two days to soak up each other's stories, ideas and passion.

(* Diverse in interests, experience, and gender, but not race; the group in the Mission Theatre was almost as white as Portland itself.)

In a stroke of inspiration, the organizers managed to get enough sponsorship to not only feed us but provide an open bar — that's right, I said an open bar — every afternoon. Which is nice, but I'm sorry to say I can now never go to another conference unless there is free booze every day starting at noon.

There were twenty-seven talks altogether, as well as some ad hoc lightning talks. They will all be available on YouTube but so far they are not sorted or tagged, just listed under the account of the company that did the videoing.

Here is my list of standout talks from the conference:

Matthew Butterick's Typography for Docs (NSFW: swearing) didn't teach me a whole lot (which is good considering typography is one of the many things I charge money for) but Matthew is charismatic, funny, and opinionated. And I love that he didn't have a slideshow, he just clicked around some tabs in a browser window.

Matthew outlined four important decisions in typography:

  1. Font choice (he likes Charis, Charter, and Adobe Source Sans for the web)
  2. Font size (smaller than you think for print; bigger than you think for the web)
  3. Line length (between two and three lowercase alphabets per line)
  4. Line spacing (between 120% and 145% of font height)

(I know, this blog fails terribly at at least two of those. Cmd-shift-=!) Among other things, he warned us to be careful of misuse of emphasis; anything dark catches the eye, so you don't want a lot of darkness in your navigation — save it for headers and other clues to document structure.

Matthew Butterick wrote a book called Typography for Lawyers which I will probably buy.

Kevin Hale's Getting Developers and Engineers to Write the Docs is misleadingly titled; it is really more about customer support and retention than documentation, although documentation plays a part in both those things. The punchline is that at Wufoo they got developers (and everyone else in the company) to answer the tech support phone. My favourite line: "After the second or third ring of that phone, with the exact same problem, the engineer will stop what they're doing, fix the problem, and you don't get phone calls for it anymore." (That's a paraphrase of a Paul English line.)

Marcia Johnston's Write Tight(er) — (no video yet) was about how to write concisely, with the right number of words and no more. She argues that wordiness is bad when paying for translation and when people are reading on small screens, but editors everywhere know that concise writing is easier to read and comprehend.

Marcia provided a list of ways to write tighter. Get rid of:

  • variations on "to be"
  • -ly words and other flabby adjectives
  • "very", "just", "such", "so", and "really"
  • negative constructions
  • "begin to" and "start to"
  • (or be suspicious of) "of"-phrases: "in light of", "in spite of"
  • "proverbial"
  • "different" in "many different" or "three different"-type constructs
  • the passive voice

And of course, with all these guidelines the rule is to apply them, unless it's better that you don't. Oh, English.

Marcia's book, Word Up!, will be available on April 27; I'll probably buy it, too.

Nóirín Plunkett (or Pluincéid on Twitter, but I guess that's just too open to mangling) did a talk called Text Lacks Empathy (also not posted yet). It's about how to put the emotion back into casual written communication.

Nóirín had some lovely metaphors. Being social is, for introverts like her, like working in a virtual machine; she can still do all the usual things, but it takes a little more processing time. Tact is like a filter: some people apply it on their output; some people apply it on input from others. If it's not applied on either end (i.e., if someone assumes the listener will apply tact on input and so doesn't apply it on output), offense can result. Similarly, if tact is applied on output and input, content can be lost.

She also pointed out that in an emotional void we tend to assume negative emotion. That is, if you haven't heard anything specific about someone's emotional state for a while, you tend to assume that they're angry or annoyed at you.

Nóirín had some suggestions:

  • Understand expectations: where is the tact filter generally expected to be applied in your organization or relationship?
  • Zero is not negative: don't assume that no emotional communication implies negative feelings. If in doubt, ask, and always assume good intent.
  • They don't know how you feel: you have add emotional content to your writing in a way you don't have to add it to face-to-face communication. Express your emotional state with words, use emoticons, or change to a more emotion-rich communication channel: email < IRC < voice < video < real life.
  • Perception is reality: if someone feels attacked, it doesn't matter what your intent was, they will react as if they have been attacked. You have to deal with their emotional state first, before you can return to the content of your conversation.
  • Active isn't always better than passive: take advantage of English's passive voice: "You broke the build" is aggressive and causes those emotions that you then have to deal with; "The build broke" allows everyone to save face and get on with fixing the problem.
  • If it doesn't matter, do it their way.

Unfortunately Nóirín ran out of time and didn't get to talk about the last points in her slide show — I'd like to see the whole talk sometime.

It struck me that many of Nóirín's points apply to parenting. When you're dealing with an upset child, you do have to manage their emotions before you can teach, discipline or advise; they literally cannot take in any information while they're upset. (As my nanny told my mother once, "They can't hear you when you shout at them.")

Assuming good intent is vital; it's one of Alfie Kohn's 10 Principles of Unconditional Parenting. And finally, "if it doesn't matter, do it their way" is another way of putting one of parenting's most important mantras, "pick your battles wisely".

I have no idea if Nóirín has written a book, but I'm sure she will eventually.

Finally (for this post, not for the conference), Daniya Kamran's Translating science into poetry was beautiful and thought-provoking. She didn't offer examples or concrete tips, but a series of ideas to consider when writing:

  • Constant vigilance; remember you are writing to impress the reader and earn their continued attention.
  • Immortality: write as if your writing is immortal; write to transcend time.
  • Dilemma: poetry is about conflict and questions; introduce them into your writing.
  • Bias: have a point of view; be the expert.
  • Error: poetry is about things that have gone wrong; treat crises as part of the cycle, not as a negative consequence.
  • Reiteration: poetry uses it liberally; after each complexity, bring your document back to its purpose.
  • Metaphors allow the reader to participate in creating meaning, and so they connect to your writing more deeply.
  • Elegance is important.

Tim Daly's talk on Literate Programming was entertaining; Jennifer Hartnett Hender's talk about sketchnotes was thought-provoking. Heidi Waterhouse did a talk about writing search-first documentation to make your documents findable. Ana Nelson's talk about Dexy was thrilling (even though I was exhausted and understood about 14% of it). There were a couple of good talks about the importance of documentation, and another couple about how to convince your company and colleagues to take documentation seriously, and even to write it themselves.

There were plenty of interesting talks and lots of great people at Write the Docs. I don't know if I will go next year, what with not being a tech writer and all, but I'm glad I went this year and I would recommend it to anyone who creates documentation and works with developers.

Write the Docs is on Twitter, where they have posted links to some write-ups of the talks and will hopefully link to videos when they are up.