Blog-o! Notes from latte.ca

Sat, 20 Apr 2013
Amy Goes to Portland

In order to go to the Write the Docs conference that I wrote about in my last post, you might suppose, correctly, that I had to go to Portland, Oregon. My last adventure was my trip to Japan in 2011, so I was ready to get away.

There are lots of ways to get from Toronto to Portland; I chose to go via Vancouver on Air Canada because I heard from Twitter that, while Air Canada is bad, the American airlines are worse. As usual, I didn't have any trouble with Air Canada and arrived in Vancouver only slightly cramped and squashed.

We flew into a storm on the way from Vancouver to Portland, and when we were almost there the plane got hit by lightning. I wasn't terribly happy about that; I couldn't think of a time I had heard about planes being hit by lightning and it ending well. The pilot didn't seem bothered, though, and apart from some turbulence and the people behind me panicking, we landed without a problem.

Portland was warm and moist and smelled wonderful. I got a ride to the Hotel deLuxe from an Internet friend, and we had a chance to gossip and talk to her little guy about Superman and the fact that he couldn't reach his bits of paper with "S" on them.

The Hotel deLuxe was built in 1912 and recently restored with a vintage movie theme. It's a luxurious old-timey hotel like a smaller King Eddy. My room had floor-to-ceiling velvet drapes, crystal deco-style light fixtures, and white subway tile in the bathroom. The bed was furnished with thick, heavy sheets and more pillows than I knew what to do with. (So, more than two.) There was also a pillow menu, so you could order an even better pillow than the umpteen already there, and a holy book menu so you could request any one of about twelve holy books. I approve of the breaking of the Gideon hegemony.

After I got settled in I decided to go for a walk to wind down after travelling all day. Powell's Book Store was nearby, labelled as an attraction on the hotel map, and open late, so that was my destination.

The area around the hotel was dead at that time of night; there are some offices, a church, a theatre with nothing going on. Obviously I wasn't familiar with the neighbourhood so I didn't know how nervous to be, but there were a few women walking around and biking alone, so I decided not to be nervous. After a couple of blocks I came to Burnside Street, which was a little livelier.

Powells is astonishing. It's a multi-storey used book store which covers an entire block; it's a shrine to books. I could have spent the whole weekend there, but I managed to escape after about an hour and a half with only a few books and a couple of gifts for the girls.

The next day was the conference, which I already talked about over here. I woke up early (still being on EST, three hours earlier than local time), worked out in the hotel's small-but-effective gym, then had a proper cooked breakfast in the hotel restaurant. (I don't know why, but hotel breakfasts are the height of luxury and self-indulgence to me.)

I walked to the conference site in plenty of time, so when I got there the doors weren't open yet. There was a short line of grumpy-looking people waiting to get in (and one person who looked pleased to be there). I was happy and well-rested so I didn't want to stand in a grumpy line, but I wasn't feeling outgoing enough to talk to the one happy person, so I went for a walk around the block instead.

By the time I got back the doors to the Mission Theater were open. It's another old building (Portland doesn't seem to have Toronto's love of knocking old buildings down): a theatre with a balcony and a bar.

As I said in the other post, the conference was great. We were served lunch and there was an open bar (!). The line for lunch was really long, so to pass the time I had a beer; the first day I asked for something "not too bitter" (because I know Americans love really bitter ales); the drink the bartender served me was delicious and indeed not too bitter, so I asked what it was: a Nebraska Bitter. Good thing I let him choose.

I took a break from the conference and walked down a few blocks to get a coffee from Barista — some of the people at the conference suggested it as the best local coffee place. (It was delicious and, after three days I'm officially spoiled for non-awesome coffee.) I also stumbled on Oblation Papers, a paper and print shop with beautiful, quirky handmade cards. Like so many places in Portland, the store is just the front desk for a tiny factory — they actually make the paper right on site. There's also a budgie.

I really like Portland. I don't really understand how the economy of Portland works because there seem to be lots of businesses which employ people to make things by hand, and sell the things for reasonable price. You can get vegan food everywhere, and wherever you can buy coffee, you can also buy beer.

Monday night the conference organizers had some events planned; a night at a video game arcade (with infinite quarters), and a couple of informal gatherings nearby, at a beer place and a coffee place. The video game arcade had dozens, if not hundreds, of video games and pinball games, but nothing that appealed to me (unsurprisingly — I have never liked video games). They had DDR but no-one was playing. I ended up going around the corner to the coffee place — not only coffee, but beer and computers you could rent time on — but there was no-one from the conference there. I was tired and hungry anyway, so I had a plate of nachos, read Twitter and went back to the hotel.

On Tuesday I tried World Cup Coffee, which was better than Starbucks but not as good as good Portland coffee (told you I'm spoiled). They were experiencing a small fire in one of their coffee roaster, but they managed to make me a coffee anyway.

Wednesday morning I woke up even earlier, packed, and had another fancy hotel breakfast. Then I caught the Max train (just around the corner from the hotel) and rode all the way to the airport without a single transfer. So awesome! I wish I lived in a non-world-class city that had decent transit to the airport.

I entirely failed to get any good gifts for my cat-sitters, so I hoped I would be able to get something at the airport. I was lucky; turns out the Portland airport has awesome retail, including a store called Made in Oregon which has a great selection of interesting, actually-local food and gifts. I got hazelnuts, tea, chocolate and saltwater taffy for the folks back home.

[Posted at 22:41 by Blake Winton] link
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