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:
- Font choice (he likes Charis, Charter, and Adobe Source Sans for the web)
- Font size (smaller than you think for print; bigger than you think for
- Line length (between two and three lowercase alphabets per line)
- 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
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"
- "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
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
- 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
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
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
- Dilemma: poetry is about conflict and questions; introduce them into
- 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.