Category Archives: Tips

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:

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!

Irssi in Terminal on GNOME 3.12 in Fedora 20.

A lot of people I know like running the Irssi IRC client in a terminal, whether in a terminal multiplexer like tmux or GNU Screen. Me too!

I also love running the latest GNOME releases. So when GNOME 3.12 was released and available for Fedora 20, I followed these simple instructions, courtesy of Fedora Magazine and Ryan Lerch, to install it on my system.

I discovered a new feature in the GNOME Terminal is that keys Alt+1 through Alt+0 are mapped to allow you to quickly navigate to the first ten tabs in Terminal. This is super-useful, but because those keys also happen to map to the shortcuts in Irssi for switching to your first ten IRC windows, I couldn’t use them in Irssi. Since I use that function a lot more often, here’s how I fixed it:

  1. Open a GNOME Terminal, and from the quick menu in GNOME Shell’s top bar, choose Preferences.
  2. Under the Shortcuts tab, locate the Tabs list.
  3. For each shortcut from “Switch to Tab 1” to “Switch to Tab 10,” click the shortcut to select it. Then click the entry under Shortcut Key. Hit the Backspace key to remove the existing shortcut.

Now you can use your Alt key combinations as before in Irssi. Have fun!


Changing font size in GNOME 3.4 on Fedora 17.

Someone asked me a few weeks ago whether I knew how to change the default font size in GNOME 3 on Fedora. I have all my boxes on Fedora 17 since before the release, with GNOME 3.4. I had to admit that I’d never looked for how to change the font size in GNOME, but it seemed like something you might want to do, especially on extremely small or large displays. I hadn’t bothered to write this up, but I thought given a news story this morning that it might be useful to others.

I had no clue where to start. So how did I find it? I went to the Overview mode by hitting the super key (you could also use the Activities hot spot or Alt+F1). Then I started typing: f o n t. The first thing that comes up in the menu is the Universal Access setting. I opened it up (I just hit Enter, but you could mouse to it just as easily), and sure enough, under the “Seeing” tab there’s a setting for the default font size!

Finding old test packages in Koji.

After I answered a question on the devel list today about getting one’s hands on an old testing package for Fedora that had been obsoleted or removed, Josh Boyer one-upped me by providing some easy instructions. I figured I would tip my fedora to him by building a blog post on his work. Nice one, Josh!

When someone builds an official Fedora package, whether it ultimately gets moved to stable or not, there’s a record for it in Koji, the Fedora package build system. You can use the search bar on the Koji website to find the package or build you’re inerested in. In the resulting page, you’ll find the build is labeled with the git commit from which the build came — it’s the long checksum in the “Task” line.

The package may not be there anymore, but that git label is all you need. It represents the position in the repository history from which the packager built that package. You can find that point in history and re-execute the same steps. You can then clone the package’s git repository, reset the HEAD to the proper commit, and send a scratch build to the Koji builder. Once the build is done, you can download the results.

Caveat: It’s possible that other package changes in Fedora might make a build of that exact point in history difficult later. Be aware this solution isn’t perfect, and you may simply want to find an alternate build in Koji that still exists and suits your purpose, or use the latest updates-testing or stable package instead. But in the hopes people find it useful, here are the commands, assuming the package name is “foobar” on Fedora 16 and the git commit of interest in starts with “0123abcd” (and let’s hope I do better than in the last post in which I gave tips):

su -c 'yum install fedora-packager'
cd /tmp
fedpkg clone foobar
cd foobar
fedpkg switch-branch f16
git reset --hard 0123abcd
fedpkg scratch-build
The URL that comes back to your console is the task for that build, and you can use that to drill down into the individual package build tasks as needed later. Remember, scratch builds are not retained for very long, so if you want the package, try to download it relatively soon after you build it.

Here’s another hint: the git reset command above rewrites your index and your working tree, so essentially you “lose” the later history of the repository. However, git is so awesome that this is not a permanent condition. If you really need to reset the git repository back to its original path, you can use git reflog to find the reference to the checkout you did of the “f16” branch, and reset to it (probably something like this):

git reset --hard HEAD@{1}
Once again, it’s important to point out that the above is not for the faint of heart. If you don’t understand the ramifications of trying withdrawn, obsolete, or deleted packages on your Fedora machine, or packages intended for testing, don’t use them. That being said, testing packages is a really helpful activity, and there are all sorts of easy ways to keep testing contained on your system, such as using virtual guest machines. So the intrepid needn’t be shy!

Autotitles in screen.

This comes in really handy in ~/.screenrc:

shelltitle '$ |bash'

Then add this in ~/.bashrc:

export PROMPT_COMMAND='[ "$TERM" == "screen" ] && echo -n -e "\033k\033\\"'

Restart screen in a fresh bash session and enjoy.

UPDATE: I stupidly screwed up the screenrc line because I did it from memory instead of copypasta. No cookie for me!

UPDATE #2: Aha, found that something in the innards of my blog software was removing an extra backslash that was needed in the export command above. Sorry for the mess.

You can ring my bell.

I’ve been using xchat-gnome on Fedora for quite a while. It’s been my default chat client because the way it notifies about private or channel messages fits well with my workflow. However, recently I’ve wanted more often to encapsulate my chat in a screen session along with my other work. Of course, the obvious answer to this is Irssi, a popular text-based client.

I still tend to also have a web browser open often in a GNOME session, though, so notifications are very useful to me. For a while I used Irssi with a simple plugin script that calls notify-send to create popup notifications. However, I hadn’t used it since the GNOME 2.30-2.32 days, and I found this script had developed drawbacks as it aged against the new GNOME 3 environment.

For example, the notifications would fill up the notification tray over the course of the day. Clearing them required an action for each individual notification, which was tedious to say the least. Also, the --timeout argument to notify-send seemed to no longer work for me to make the notification leave the notice area after a specific length of time.

What I really wanted was a solution that would act more like many of the other native GNOME applications. Appointment notifications or email in Evolution, for instance, “stack” in the notification area into a single icon, with a number that tells you how many notices have been received. Thankfully a few GNOME folks — Marina, Matthias, and Ray — kindly gave me some advice on solutions.

First, there’s a hint called transient for notifications that lets them evaporate from the notification area after a specific time. (You can find the full notification spec here if you want to dig a little deeper; I found it really educational.) This was a step forward because it kept the notices from piling up in the notification area ad infinitum. For instance:

notify-send --hint transient:1 'subject' 'message'

Unfortunately, just using transient meant I’d likely miss some notices if I was away when they came in. I wouldn’t know someone was looking for me unless I switched to my Irssi window to look — which is precisely the thing that notifications should prevent. Nevertheless, it’s a really useful hint, so file that away for later reference.

Never fear though, because again the GNOME folks passed on some good advice. The stacking effect is handled automatically by GNOME Shell if the notifications are issued from the same PID. Aye, there’s the rub! The Irssi plugin I was using made this impossible, because it called the notify-send executable for each message, meaning a new process for each instance. What I really needed was a single process listening on the session D-Bus that could kick off a notification.

So what I came up with can be found here. If you want to just test the listener, maybe because you don’t use Irssi, try this command with the listener running:

dbus-send --session /org/irssi/Irssi org.irssi.Irssi.IrssiNotify string:'subject' string:'message'

The listener is just a dead-simple (or maybe I should say brain-dead, given the quality of code) Python script. I put it in ~/bin with the executable bit set on, added it to my list of applications that launch with my GNOME session using gnome-session-properties, and added the new notify Perl plugin for Irssi to my ~/.irssi/scripts/ folder, with a symlink from ~/.irssi/scripts/autorun/ so it starts whenever I run Irssi. The stacking of notifications makes them very easy to clear with one user action — aaah, much better!

Future thoughts:

  • One flaw with this method (I’m sure there are many!) is you’ll get notifications even if you’re actively looking at or talking in the IRC channel where a message comes in. It’s easy to add logic to alter the behavior based on that, but what complicates matters considerably would be trying to make this script understand when Irssi was in the active screen window — or when the screen was the foreground window in GNOME.
  • It might not be kosher for me to have used org.irssi.Irssi as a service name in D-Bus. After all, this isn’t official or part of the Irssi project at all. But as I understand it, you could use whatever name you liked, as long as you weren’t trying to claim a service name already in use.
  • You could make this work system-wide by packaging a real .service file for D-Bus along with the Irssi script.
  • When we were discussing the technical issues above, Ray told me he was actually looking for something similar. With any luck, he’ll find something annoying in my stupid solution he can’t live with, and he’ll add some magic GNOME-ishness to make it awesome. See what I did there? 😉

On burnout.

Bruce Byfield has published an article on burnout in community projects, to which I was happy to contribute some thoughts. Overall I believe the thoughts people shared in that article, while not surprising or radical, can help people avoid putting themselves in a burnout situation. Moreover, they can potentially help someone realize that a friend may need a helping hand before they run smack-dab into burnout themselves.

One of the striking (but again, not surprising) bits Bruce wrote in the article was this:

The stress may be increased because the first generations of community members are now well into middle-age, and some are starting to have trouble working the hours to which they are accustomed, either because of reduced stamina or family obligations.

This statement really hit home with me, because in a very time-compressed way I went through a seismic shift in my work/life balance twice in just the space of a couple years. I was feeling somewhat in a confessional mood today, so I figured I’d try and write about my brush with burnout in an honest and not overly edited way. Like Linus, I don’t think I ever really hit a wall. Whether by luck or conscious introspection, I was able to avoid that disaster. But I did see it approaching in the distance, and maybe an explanation of what I did about it will help someone else who sees a reflection in my story.

I started in FOSS long after the very early, pioneering days. I joined the Fedora Project in 2003, by which point my wife and I were already expecting our second child. Since I was more of a homebody by that point, I found it convenient to work in a community software project. I was already hanging around the house more than I used to, but now I could plop down with a laptop and do something extra for my fellow man at night or on the weekend. Meanwhile, my day job was fairly regular, and no remote work was possible, so my work ended when I left the office.

Taking a job with Red Hat made open source the focus for most of my waking hours starting in 2008. By then my son was 4, my daughter was almost 7, and there was plenty to get done every single day on both the home and work fronts. During the next two and a half years, my work schedule became radically different. 12-14 hour days were the norm, and still there was always more to do. I would say that working from home made it easy for me to focus too much on work, and not enough on other important things, like my family. My wife, thankfully and far beyond the call of duty, took up the slack at home.

I joke sometimes to others that one of my purposes in life is to be a cautionary tale, and that definitely applies to my work/life balance problems my first 18 months at Red Hat. I only saw my kids for a small amount of time daily, and to this day I worry that I don’t have enough memories of my daughter’s early grade school or my son as a preschooler. I made it to the obligatory stuff, of course, but it wasn’t real quality time. Mostly when I wasn’t working, I was thinking or worrying about work. Breakfast, lunch and dinner were rushed events after which I’d practically sprint back to the computer, fearing about all the things I wasn’t getting done. It was a very unhealthy approach to work.

At some point partway through my job as FPL, I came to a realization: One day I’d wake up and my kids would be going off to college, and I’d be thinking, “Wait, you can’t go yet, I’m not ready.” Something had to change, and that something was me. But it couldn’t be as simple as just working less. There were lots of people counting on me for different things in Fedora, and many of them were giving their precious spare time for our project. So I had to figure out not how to work less, but how to work smarter.

I ended up overhauling a lot of my tools, for one thing. I tried to find more efficient ways of getting things done, so I could maximize my output per hour. I changed physical and network setup of my office so I had more flexibility and fewer interruptions. I also tried to refocus my work on critical path topics — for instance, trying to spend the majority of my day working on problems that would allow volunteers to get things done. And I started hitting the gym almost every weekday so I could energize the rest of my day. (I’ve fallen off the wagon the last couple of months, but I’m heading back this fall, since I’ve definitely noticed the difference in my mental attitude and energy without it.)

But that’s all mechanical, and not really as difficult as the psychological aspects. I also had to confront my own focus on trying to get everything right, and learn to forgive myself for making mistakes. (Especially since I tend to make so many.) Rather than spend a lot of time each day trying to make everything 95% correct, I needed to spend far less time to get things 75% or 80% correct, and trust other people to help me figure out the rest. When you think about it, that’s part of the open source way, really. We often say “Don’t let perfect be the enemy of good,” and I found that was equally applicable to several parts of my life, including my approach to working in an open source oriented job. Amber Graner talks about “letting go” in Bruce’s article, which I think accurately describes the conscious approach I had to take.

There’s an old saying that you’ll never hear someone on his deathbed say, “I wish I’d spent more time at the office.” I agree with that — in general, I don’t want to have regrets about how I live my life. After all, that’s why I came to Red Hat when the opportunity of chairing the Fedora Project arose. I didn’t want to look back and think, “If only….” Now I realize for me to be at my best for open source, I’ve got to be better at balancing my obligations. I have to let go of the things I can’t do, or can’t do well, and focus on the areas where I can make a difference.

Not all those areas are in work, either. I can make a big difference in my family’s quality of life by doing a better job focusing on the important parts of being a parent. Over the last couple of years, and especially this past year, I’ve started to take better advantage of opportunities to be off the keyboard and building experiences with my family. That might mean going to historical sites or museums, traveling to visit friends, or just doing fun things together, but I feel it’s made me better equipped to deal with job stress when I know I’m doing well by my family.

Of course, it’s not like I’m doing this perfectly. I still have problems with balance, but at least I feel like I have the experience now to identify them and hopefully deal with them. As I mentioned, this is somewhat a confessional article, but I’m not looking for pep talk (or, obviously, the opposite). Rather, I just wanted to share something I care deeply about, which is that I want you, Gentle Reader, to be happy in what you do and find a balance that suits you. I’d love to hear your story about how you’ve found balance, or the challenges you face in doing that. Feel free to write a comment, but I’d love to see trackback posts where you don’t feel constrained by a little comment box.

Truer words, no. 54.

Good article by my buddy John Poelstra with which I vehemently agree. I’ve been doing something similar with email for a couple years now using offlineimap, synchronizing a few times a day rather than keeping an app open all day or making myself the slave of instant notifications about new email. It’s made a huge difference in my productivity. I’m not perfectly disciplined about this, but more often than not these days, I tend to ask myself before syncing my email, “Is there something coming that you need in order to make progress on your most important task right now?” Often the answer is no.

Sometimes I might be tempted to pull email out of habit, or because I need a break from my current task, or because I’m procrastinating. In all these cases there are better remedies available. Habits can be an indicator of not thinking through what you’re doing, and I’m trying to get better at that in general — so breaking this habit is something I work at constantly. If I need a break, I try to just switch tasks instead, or in the case of overall fatigue, I leave my office for a few minutes to get some perspective. Sometimes a short walk or playing with the family dog lets me come back refreshed and ready to focus. Procrastinating is a special problem that I just try to meet head on, although again I’m not the epitome of doing that well.

Email and communication are vitally important in my job, but they are not the only important thing I need to do in my job. It’s important to keep your tools in perspective and remember that the thing that makes you valuable to your employer is not just your ability to communicate — it’s the ability to communicate something worthwhile. And communicating something worthwhile often requires you to be able to focus and think clearly without yielding to the distraction of your communication tools.

Help for the hapless.

I often make typos, and sometimes I hit a key combo when I don’t mean to. (That never happens to you right? Right?) One of my most common goof s is hitting several of the same key combination in a row, such as Ctrl+D to exit shells. I might find myself in a situation where I’m running a secure shell session in a terminal, and after I exit out of several subshells or a screen session with Ctrl+D, I inadvertently hit Ctrl+D one extra time, and exit the shell I wanted to keep.

Now ordinarily this wouldn’t be a problem — just run ssh to get back into the box, and Bob’s your uncle. But every once in a while it can be disastrous, for instance when you’re piddling around with the network on a remote box, or if the SSH session in question is providing a tunnel for some other applications in progress.

I do a couple things to avoid this problem. The first is to use the ControlMaster option with my SSH sessions (the shorthand option is -M). More than one instance can share the same connection. The first instance acts as a master, and you can configure where to store the socket it’s using. Additional sessions you start on the same host and port will share the connection.

This has a couple effects, and one of them is fast startups for the second and following connections — since the connection has already been made and you’ve authenticated, all that remains is to start up the session (such as a login shell). Another effect is that you can shut all the connections down (somewhat forcibly) by shutting down the master session!

Take my situation for example. I set this option in my personal configuration file (~/.ssh/config), because I often have multiple connections open from different applications to the same host. Sometimes those connections aren’t all obvious. For example, my music library is on a remote host that I access with Rhythmbox via SFTP (FTP over SSH). The SFTP connection will open automatically when I start up Rhythmbox — I get prompted for the passphrase, of course, because I don’t like to store that anywhere — and the volume is mounted via Nautilus, the GNOME file manager.

Now imagine later on, I open a secure shell to the same system for other work. If I unmount the share for some reason, having forgotten it was the first thing that started a SSH connection and thus inherited the title of “master,” boom! My other SSH session gets disconnected. Yikes. And the reverse sometimes happens too — I might stop the SSH session I started in the morning, and if it’s the master for the music library connection from Rhythmbox, my music might stop cold.

So obviously, I like the positive side effects of this setting, but not so much that last, negative one. Especially when I have a  habit of shutting down the master carelessly. Recently I’ve started using is the -N option to help solve this problem, which doesn’t execute anything on the remote side after authenticating. I think I saw this hint elsewhere, and found it intriguing.

You don’t get a shell or anything else after login, just an open socket. So at this point you can background the job (Ctrl+Z in the bash shell), and close the terminal it’s in. The SSH socket stays open peacefully and invisibly in the background like a Zen master, waiting to do your bidding. Now you can open up additional sessions on that system with ssh remote-host-name, and they pop up quickly. No matter what interactive shell session you close, things keep humming right along. (If you really need to close the entire connection and all shared sessions with it, you can just kill the master connection that’s still in the background.)

Since I use a variety of SSH tunnels for different stuff, the -N switch has made it much easier for me to keep my tunnels alive and working even if I have to logout of my GNOME session. If you’re more trusting with keeping your SSH passphrases in the GNOME Keyring, you could start up lots of these background connections with minimal keyboard interaction. If you wanted to be slightly more clever, you could even set up a notification that would inform you if one of the background sessions failed (that will still generate an error condition on your end, the client end).

This is not the only way to use SSH more effectively, but this method solved my problem and I hope you find it useful, and that it helps you complete your work a little more efficiently. I’ve started a category for hints like this on my blog, and I’ll continue to send useful tidbits here for your reading pleasure. If this information helped you, or if you want to make an additional suggestion, please feel free to use the comment form, or trackback from your own helpful blog entry.