Let Monty Python help you build techcomm lists correctly

Monty Python offers a most entertaining reminder about the safest way to introduce bullet lists in their sketch The Spanish Inquisition: Omit the number of elements in the list’s introduction. This allows you to add elements to the list without having a wrong introduction. In the words of Cardinal Ximénez (Michael Palin): NOBODY expects the [...]

Writing to create context to think – and work

The skill of technical communication is to create a context in which other people can work. – This concise insight helps me to stay focused on my users and their tasks, even if it’s not totally original. I came to it via an article by Tim O’Reilly in his Financial Times article “Birth of the [...]

Favorite tech writing dogmas

I’m usually wary of dogmas, but some just won’t go away, they assert their eternal truth in uncanny ways. I’ve recently found some new ones, so I now have four five tech writing dogmas: A new tool will not fix broken processes. No matter how cool you are as a software company, don’t build your [...]

What’s in a (serial) comma?

An example of a missing serial comma got tweeted my way which was too good to be true: Among those interviewed were his two ex-wives, Kris Kristofferson and Robert Duvall. And here’s the guy who was married to both, Kris and Robert…

How to wash George Harrison’s car

This is from 1962 when George Harrison was trying to break into tech writing, playing guitar on the side. He’s not bad for a 19-year old. To wit: He presents the procedure step by step. He uses the imperative for clear instructions – though he lapses into conditional “should”s occasionally. He speaks to his reader’s [...]

Managing: Instruction vs. communication

I’ve found an enlightening opposition in Jurgen Appelo’s presentation “The Dolt’s Guide to Self-Organization“, slides 54-55: Managing a lifeless system is all about instruction. Managing a living system is all about communication. What struck me was that we tech writers often consider task-based instructions in documentation already better than feature-based system description. But seen from [...]

How advertising is the opposite of documentation

You know that documentation and advertising are at odds, if you’ve worked in either for any length of time. Here’s a conspicuous definition of advertising that’s pretty much the opposite of what documentation does: I want to make the public aware of something they don’t quite yet know that they know – or have them [...]

The dangers of PowerPoint

Every time you make a PowerPoint, Edward Tufte kills a kitten. – Mark Goetz I picked this up as a ‘re-re-re-tweet’, and the original sleeper post from last November called “My new wallpaper” has a cool wallpaper design worthy to go onto a geeky t-shirt! Oh, and here’s a blog post “Dilbert on PowerPoint Presentations” [...]

Getting sequences right

The M*A*S*H episode “The Army-Navy Game” illustrates the importance of getting sequences right in technical writing. Blake and Trapper John are trying to defuse a bomb: LT. COL. HENRY BLAKE (reading instructions) And carefully cut the wires leading to the clockwork fuse at the head. TRAPPER JOHN (cuts the wires) LT. COL. HENRY BLAKE But [...]

The rights of the reader

Some lighter fare today from Daniel Pennac. The French novelist formulated “10 Rights of the Reader”, plus one warning. They are aimed at readers and writers of fiction, but no doubt readers of documentation take several of these liberties, too: 2. The right to skip. 3. The right not to finish a book. 8. The [...]