Blog-o! Notes from

Sun, 14 Apr 2013

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.

[Posted at 00:11 by Amy Brown] link
Wed, 23 Feb 2011

I'm currently working with Greg Wilson on The Architecture of Open Source Applications. It's a collection of essays written by open source coders about the architecture of their projects. I'm mainly the format monkey, but sometimes Greg lets me out of my cage to do some editing. Last week he set me loose on a chapter which had some problems with structure to see if I could come up with some helpful comments for the author.

I knew the chapter bothered me, and to begin with I could specifically point to one problem: the author didn't introduce the subject of the chapter until the fifth paragraph of the second section. (He'd been talking about and around the subject until then, but never overtly linked it to what he was saying.) Apart from that I didn't have anything specific and helpful to say.

Also I didn't know what to do next.

Don't tell anyone this, but I'm not really an editor. Okay, I'm an "editor" in the same sense that I'm a writer: I edit. But I'm not, say, seasoned. Experienced. I'm new to this. So I didn't know how to approach this chapter. I tried a few things.

First I read it again. (Of course further complicating matters was the fact that the topic of the chapter is not something I was familiar with, so not only was I editing the chapter, I was simultaneously learning from it. 1) Reading it again helped me understand the subject better but I still didn't know what I needed to say to help the author make the chapter better.

Next I wrote out an outline of the chapter, to try and see the overall structure. That helped me see that the author never clearly stated the problem he and his team were solving. But I felt like the outline was too static — I wanted to be able to move things around.

So I printed out the chapter and cut it up into sections, taped together along page breaks. That was mildly diverting and passed a lot of time, but in the end all I really got was a lot of awkwardly-sized bits of paper. I couldn't do much with the bits of paper, but the act of fabricating them helped me break the chapter up into blocks, mentally. 2

After all that I finally had a few suggestions, although ironically not so much on the structure of the chapter — that's mostly fine. The problem is that the author spends a lot of time providing unnecessary details and elaborations, while leaving out the "obvious" (to him) fundamentals that people who don't work with his subject will need to know to understand the chapter. 3

What I ended up doing was rewriting the first section to clean it up and make it into an actual introduction, and asking the author to introduce some other topics more effectively (and gently) later on in the chapter. I hope I will get a chance to tighten up some of the language and take out excess material later in the editing process.

The whole process was fun but also made me very uncomfortable. As I was doing all that outlining, cutting, pasting, researching and thinking I felt insecure and kind of dumb. "Is this what I'm supposed to be doing? Is this going to work? Am I wasting time? Should I do something different?" I hate doing things I don't already know how to do, and I had to keep reminding myself that this is how you learn — you flail, you try things, you screw up, you try other things, you get better. It does take time and it does make you feel stupid, but then after it's over you know a little bit more.

(Note to Greg: I didn't bill you for most of this arduous process. The only thing worse (for me) than not knowing what I'm doing is not knowing what I'm doing on someone else's dollar.)

  1. After bashing my head against the chapter for an embarrassing amount of time I finally looked some stuff up in Wikipedia to get a better feel for the subject matter and terminology. Lesson 1: Consult other reference material if you are out of your depth in the subject matter.  

  2. Rather than chop the actual chapter into pieces, next time I think I will turn to every author's friend, the Index Card. Summarizing each section onto an index card will force me to understand the material, and the cards themselves are much easier to handle.  

  3. Next time I read a chapter for the first time, I will make a note of every time I say "Huh?" or have a question while I'm reading. My Loyal Readers should not be saying "Huh?"  

[Posted at 22:28 by Amy Brown] link
Sat, 20 Nov 2010

I made a book! Okay, I didn't write it, and I didn't really edit it, but I sure turned it from a giant RTF into three beautifully formatted, stylishly covered volumes:

Support independent publishing: Buy this book on Lulu.

[Posted at 21:47 by Amy Brown] link