Tag Archives: editing

Writing to be read.

Here’s my point (TL;DR): Write to be read.*

Where do I get off?

As you read this, don’t forget: I’m speaking from experience as a bad writer of email! I’ve made every mistake I point out here, and most of them countless times over.

I have lots of room to improve as a writer. But in the same way, I’ve improved greatly over time. Years ago, my email messages tended to be long and flowery. They were filled with unnecessary qualifiers, adverbs, parentheticals, and asides. You name the writing sin, I committed it. It made my writing hard to read. That meant I often had to repeat myself in writing, on the phone, or face to face to make a point. Finally I realized this was due to my poor writing habits.

I learned that beautiful writing wasn’t necessarily wordy. Beautiful writing is successful writing. In open source and in business, successful means you get your point across. This is doubly true in an environment where everyone’s drowning in email. While there are certainly occasions that call for florid prose, the office or mailing lists usually don’t. I realized to truly affect colleagues, I needed to think more about writing to their expectations.

What makes for good email

If you work in open source, you probably use mailing lists. A mailing list efficiently shares information equally with many people at once. Your goal in writing to the mailing list is to inform and influence the list readers. Those people are your audience.

But your audience probably doesn’t have an infinite amount of time for email. At least, they don’t if they’re productive. I assume most people want to be productive, in open source or otherwise. They spend no more time on email than necessary. Instead, they spend their time on productive work — coding, creating, testing, doing.

This doesn’t mean email is wasted time. Ideally, email helps you stay informed, and be more productive. Those aren’t the only hallmarks of useful email, but they’re important for our purpose here — understanding our audience. The information you get from email should help you (1) reduce wasted effort, and (2) produce better work. If these things don’t happen, email stops being productive.

But here’s the rub: even an informative email may be unproductive! For example, if email causes you to waste more effort than the improvements it brings, it’s into unproductive territory. I find this often happens when email is hard to read. Here are some reasons why this might happen:

  • The information is too dense. If you’re making too many points at once, your writing becomes hard to follow. Sometimes this happens because you haven’t been careful with logic. Sometimes it happens because you haven’t organized your thoughts.
  • The information is in fragments. I see this happen on mailing lists when writers make points inline, instead of taking time to write a cohesive reply. After one or two replies, the discussion becomes much harder to follow.
  • The information is hard to find. When the language obscures your point, your email becomes unproductive. This can happen sometimes to writers not using their native language. But I find it happens just as often to native speakers, even mechanically “good” writers. That’s the case I concentrate on here.

Are we reading what you’re writing?

Have you ever spent a long time writing a big email, only to get little or no response? (No one loves the sound of crickets.) You probably started out with great intentions. You wanted to be informative and helpful. But you defeated your own purpose with sheer volume of information.

Perhaps you thought, I want to explain myself perfectly. That way, no one will misunderstand my point. But in doing so, you buried the real point in the explanation! Now you’ve made it harder for your busy audience to understand you. It’s arguable whether you even solved the problem you wanted to. After all, concise writing often makes your point more clearly.

In a way, you optimized for a corner case (as a developer might put it). And by doing so, you left your core audience behind. They’re the very people you hoped to inform or influence! Worse yet, over time that core audience becomes less engaged with you, your thoughts, and your writing.

Take me for example: like a lot of people, I’m busy. I’ll bet your core audience members are, too. If it takes me 15 minutes to read your lengthy email to pull two points from it, I may well give up before I succeed.The more time I spend to decipher an email, the more time I lose for more productive tasks. That 15 minutes is a lot of productive time to spend on one message!

But the problem grows worse over time. I usually have expectations about whether email will return the time I invest in reading it. Just like any investment, past returns don’t guarantee future ones. But they do tend to guide strategy. So I may start to set expectations about the value of your email. The more often I run into this problem, the more likely I’ll ignore or defer a future lengthy email you wrote.

Writing to be read

You might think, Why do I need people with limited time or attention to read my email? If you can’t take the time to read, then I don’t need your comments.

This kind of tunnel vision is where some people go wrong. The more you restrict your audience with artificial limits, the less effective you become at achieving your goal. You want to reach as many in your audience as possible, whether they have limited time or not.

Here’s another point: isn’t your time limited, too? Of course it is! We’re all roughly the same in this respect. No one wants their time used unproductively. In other words, most people in your audience probably have limited attention to give email. So your email should be as effective as possible.

This is why you should write to be read. Make your points as simply as possible. Build your points succinctly and concisely. And most importantly, mercilessly self-edit.Licensed CC-BY-SA 2.0 by Fredrik Rubensson -- URL: https://www.flickr.com/photos/froderik/9355090806/

Maybe you’re not used to self-editing. Perhaps you tend to spin a stream of consciousness into email. Or perhaps you couch your writing in qualifiers and asides. These bad habits probably limit your audience precisely as I describe above. A lot of smart people may avoid your email as a result. You’ve missed your chance to influence them, or spark new ideas.

In a follow-up post, I’ll show ways to predict whether your writing is likely to be read. I’ll show you how to find some common warning signs and fix your writing when they show up. Believe me, this is like any skill — a muscle you can build through exercise. I’ll show you exercises that help you get read more often and with more accuracy.

* TL;DR = too long; didn’t read.

** I believe it’s not ironic to have a TL;DR in a post about being TL;DR. If you want an explanation, you’ll read on. Hopefully I’ve written that explanation clearly enough you can follow my reasoning easily. If not, I’ve overestimated my right to this soapbox!

Respecting impairments.

This tip is a short one, but it applies to a lot of people in the Fedora Project, since we all share responsibilities for writing stuff on the Fedora wiki.

I often see instructions or guidance on the wiki where the writer wants to provide a link. Often those instructions say something like this:

  • For more information, see this URL…

Yikes! Hold on a minute here — Fedora, like many other operating systems, has users and contributors who are blind or have severe visual impairments. They may not be able to “see” your link, and in their cases, you’re giving an instruction they can’t possibly follow. This usage is very common in English, so it can be a hard habit to break. I know it’s still an effort for me not to fall into this habit.

Fortunately solving the problem is easy. Use one of the following phrases instead:

  • For more information, visit this URL…
  • For more information, refer to this URL…

Ah, that’s much better, and now everyone can follow your instructions. It’s easy to fall into the trap of thinking this issue is one of “political correctness” or social niceties, but I believe it’s simpler and less controversial. Fixing this particular usage makes the wiki more accurate. People don’t “see” a reference, they refer to it. In the case of a URL, they can refer to it by visiting it. This particular language fix doesn’t make the wording awkward or bloated, so it’s well worth using the more accurate version here.

Happy wiki-ing!

XML editing with Emacs.

I’ve been using GNU Emacs ever since I started working with the Fedora documentation team years ago. I wouldn’t call myself a power user by any means, but it handles my modest needs very well. Other people may have different preferences, which is fine. (Holy wars to /dev/null please.)

In the intervening years some really nice tools have evolved for dealing with different kinds of XML documents. I used to use the old psgml-mode to do editing of XML documents, but nowadays things are even more elegant and functional with nxml-mode. In truth, I was probably late to switch, simply because I didn’t have time to fix that which wasn’t broken.

However, ultimately psgml fell out of favor and the switch was necessary. But I discovered an array of helpful configurations that made XML editing even easier than before. I use these tools for editing DocBook XML, but they’re equally powerful for other schemas as well. For instance, you could use nxml-mode to hand-edit libvirt domain files with good confidence on their validity.

You can probably find directions like these (or even better) in a lot of places around the web. What I found difficult about the process was discovering the why as opposed to the what to do. How does all this stuff work, anyhow? None of the pages I read did a great job at explaining that. Admittedly, some of them were parts of much larger works, but I just wanted to get something done, not read an entire book. In writing the above page, I thought to myself, How can I improve this situation for the next person?

The key to solving that problem was this fantastic post by Mel Chua (and her lightning talk at FUDCon Tempe) where she talked about baking croissants. Short summary: it’s not enough to write a recipe and expect people to follow it, if your goal is to get people baking who aren’t bakers by trade. You have to take the time to fill in all the gaps.

So the result is this page I added to the Fedora wiki: How to use Emacs for XML editing.

Thanks, Mel, for the great advice. If anyone finds something wrong with that page, why bother commenting here? Just edit the wiki page if you’re a Fedora contributor (in other words, someone with an account and completed CLA). I’ll get notified when you do and everyone can benefit from your changes.

UPDATE: I revised the page slightly to give some needed background information up front and make it even more Mel-icious. Also I slightly edited this post to eliminate some awkwardness from where I rearranged text.