There exists a kind of obvious procrastination, where you avoid doing something important to do something frivolous. That’s like watching old episodes of Frasier on Netflix instead of packing for a trip that starts the next day. There’s a more subtle form of procrastination, though, where you put a lot of time and effort into work that looks productive, but is really just a scheme to avoid more important work.

I spent a lot of time on the latter form of procrastination recently. In the second half of 2013, I was extremely busy with a bunch of stuff, primarily getting ready for my wedding in December. After all that activity ended, however, I found myself with a lot more unstructured time. So I returned to the project of the post before this one, Oraide. I started putting little chunks of time into polishing it and improving it. I added some tests and wrote some new docs. It looked like a good use of my time, but if I’m being honest with myself it was not. After all, I hadn’t given a presentation of any kind in months and don’t have any current plans to do so.

On February 2, I sat down for my annual review. It’s not a big thing, I just go through my filing cabinet throwing out old stuff, and laying out some goals for the year. I like the idea of doing it on Groundhog Day. First, I like the thematic overtones of Groundhog Day and, like Bill Murray’s character, spending the day improving my life. Also, it avoids the ceremony and high expectations of starting new things on January 1. New year’s resolutions are regularly-failing, grand gestures of procrastination. Before they’re even started, they are acts of procrastination, by deferring action until some special day in the future, rather than beginning immediately. For most resolutions, there is no natural reason the effort must be delayed until the commencement of a calendar year, except to avoid the effort. New year’s resolutions fail because they are wholly structured around procrastination: after all, if you do fail, you don’t have to start trying again until next year.

Anyway, after spending some time looking at what I accomplished last year to figure out what I wanted to do with this year, I had mixed feelings about the results. While I’m happy to have gotten married and admitted to grad school, I didn’t really have much that didn’t seem ephemeral or just a set up for future demonstrations of what I’m capable of. For 2014, I want more to show for myself in the form of actual stuff that I could point to and say, “See, I did that.”

I don’t want to get mired in year- or months-long projects that fail, like I did last year. Instead, this year I want to limit projects to two weeks, with something material to show for it at the end of each two week sprint.

So to start things off, I gave myself two weeks to finish off some “final” tasks on Oraide and to write this blog post. That’s not to say I’m permanently done with Oraide, just that I don’t intend to put regular effort into it anymore. The only way I’m allowed to work on Oraide now is in the form of actual needs: to work on Oraide, I need to be either be supporting an actual presentation that I’m doing, or responding to a feature request or bug report from someone else.

When this post goes up, I’ll have already started on my next project, to build some cool microcontroller-driven lighting for my kitchen. Tune in in a couple weeks to see how it turned out.

Oraide is a Python library to help presenters with live coding, demonstrations, and recording screencasts. Oraide uses tmux to create the illusion that someone is manually typing in a terminal session. I wrote Oraide because I was asked to give a presentation at June’s DC Python Meetup.

I gave an introduction to the Sphinx documentation tool. The middle half of the presentation was a live demonstration of the software, including running several terminal commands, responding to a dozen or so prompts, and writing a sample document in vim. Of course, I didn’t have to do a live demonstration; I could have used screenshots or video to show the audience what working with Sphinx looks like. But I prefer the realism of a live demo. What I don’t prefer is the prospect of typing and attempting to narrate at the same time, or the long, awkward silences of doing one and then the other, in sequence.

Instead, I wrote Oraide to bring the best of both worlds: an actual live demo, but with pre-planned keystrokes run on-demand. So I was able to do my live demonstration largely hands-free, only touching the keyboard as frequently as I would have advancing some slides, and giving me a +10 bonus to my speech skill.

Since giving my presentation, I’ve been busy moving from Bethesda, Maryland to Newark, Delaware, but in the past few weeks I’ve found some time to clean up my code, do some packaging work, and, most importantly, write some documentation for my tool. Since the tool was a rewrite of an idea I had a few years ago to control GNU Screen, I reused the name Oraide, a portmanteau of orate and aide.

The next time you need to show off something in a terminal session, give Oraide a try. The tool is open source, simple, documented, and completing the tutorial should only take a few minutes.

Earlier this week, Alan Pringle posted Adapt or die: style guide edition. Like a lot of good advice, it will leave sensible readers (such as yourself) thinking that it’s an unremarkable advisory that goes without saying. But it may also leave you uneasy that there may be writers who haven’t already learned that fussing over style guides is a bit self-indulgent. It’s quite good, though I got tripped up over what’s practically a throwaway line:

If you start a new job and don’t like a decision in a style guide, join the club and suck it up (unless you have a truly compelling argument).

I stopped on that line because knowing whether you’ve got a good argument to do something is the only genuinely hard problem in developing content, style guides included. What constitutes a “truly compelling argument” isn’t necessarily obvious. Nearly every style guide fight I’ve witnessed had at least one person who believed their quibble represented a “truly compelling argument.”

I suspect many trivial arguments can be short-circuited by having, along with the style guide, expectations about what the style guide is meant to achieve. In the absence of clear expectations, “truly compelling” is whatever proponents and opponents of a change think is important. So, I offer to you the following template for a style guide hierarchy of importance, with sample rules and sample compelling arguments:

Writability

If a rule is a huge pain to implement, it’s out. If it’s easy to do, it’s in.

Example rule: The company name is always followed by the trademark symbol.

Example argument: Seriously, you’re going to Make™ Me™ Do™ This™ All™ Day™?

Readability

Clarity is important. The style guide should favor understanding over confusion. If a rule makes it harder to understand something, it’s out. If it’s easier to understand something, it’s in.

Example rule: Never use the serial comma.

Example argument: The serial comma is sometimes needed to resolve ambiguity that cannot be resolved by reordering words.

Maintainability

Documentation should be made to last, and it can’t last without reliable upkeep. If a rule is hard to maintain, it’s out. If the rule is easy to maintain, it’s in. Special cases are special cases of pain.

Example rule: The software package’s name should be all lowercase, unless it appears at the beginning of a sentence or headings greater than level three.

Example argument: Too many special cases. The package name should always be lowercase or always uppercase because it’s way easier to verify correct usage if it’s the same usage everywhere.

Unity

There is one and only one style guide. One and only one person is the author of the style guide. That one and only one person is the final arbiter of what goes in, of what comes out, and of what adheres to the style guide.

Example rule: You’re free to end a sentence with a preposition, if you want to¹. Go nuts.

Example argument: Trick example. There is no compelling argument against the rule. Daniel’s style guide, Daniel’s rules.

Note that these criteria are not coequal, as each criterion trumps the preceding criteria:

Writability < Readability < Maintainability < Unity

Your approach might not be the same as mine (maybe you favor readability over maintainability, or the addition of some other criteria), but there needs to be a clear hierarchy of importance.

I acknowledge that this approach may lead to bad outcomes (for instance, log in and login might be argued into one strict usage under the principle of maintainability even though it hurts my English-major heart). But it’s my intention that by putting Unity above all else, one sensible person will halt any egregious style guide errors. Or to put it another way, there’s no rule that supersedes a good editor.

With clear expectations in place, style guide disputes will tend toward resolution in favor of the principle behind an argument, rather than the quality of the argument. “But Daniel,” you say, “shouldn’t good arguments win and bad arguments lose?” To which I say, emphatically, “No.” That leads to wasting time coming up with highly refined arguments for trivial style guide disputes, when you could spend that time writing the docs.

Yesterday, I caught an interesting conversation started by Mark Baker‘s tweet reflecting on the uncontroversial understanding that software developers are less productive when subjected to interruptions:

MT Why companies want writers who are SMEs. #techcomm @rahelab: Programmer Interrupted (po.st/EQpomr

— Mark Baker (@mbakeranalecta) January 22, 2013

What followed was some skepticism on the part of Rahel Anne Bailie and Kai Weber about attempting to hire writers who are also subject matter experts (SMEs):

@mbakeranalecta Companies who want writer-SMEs are like companies who want accountant-SMEs or developer-SMEs, IMHO. Kind of silly.

— Rahel Anne Bailie (@rahelab) January 22, 2013

@mbakeranalecta @rahelab Uhm, can’t writers just schedule meetings with dev’s? Or are scrum stand-up meetings interruptions as well?

— Kai Weber (@techwriterkai) January 23, 2013

I’ve heard this kind of skepticism about SME writers expressed before, almost as if there’s something improper about subject matter expertise. I’ve heard other writers talk about subject matter expertise as though acquiring expertise necessarily diminishes the abilities of a writer to communicate. And it’s an occasional insecurity of mine that being “just” a writer is inadequate. So I understand that asking for subject matter expertise from writers is a bit fraught.

In agreement with Bailie, there’s a tendency toward over-specification in hiring searches. Organizations often seek to hire a wish list, but wish lists rarely apply for open positions. For most organizations, a more realistic expectation is to hire a person who has a few characteristics of the wish list, combined with the enthusiasm and ability to learn the rest. But if an organization can get a writer SME, then they should, as it is a powerul pairing, at least in the software business.

Asking a writer to go through specifications or other documentation, or through SMEs themselves, to understand software is a bit like playing a game of telephone. Yes, the message will get through eventually, but errors routinely creep in. Specifications reflect aspirations and goals, not working software. In contrast, code doesn’t lie. Code provides a kind of clarity about software that is beyond the reach of the most thorough SME interview. A writer-programmer doesn’t have to play telephone.

At one point in the conversation, Baker asked, “which metric do [companies] care about most, developer productivity or content quality?” as if the two were necessarily in opposition. But expertise in one area doesn’t have to come at the expense of another. Companies that have SME writers don’t have to choose between developer productivity and content quality, because paired expertise is often complementary.

Consider a simple case, one I’ve faced dozens of times, in which I’ve needed to document the acceptable values for a form field. One way to deal with this is to turn to the developers and ask, “what are the accepted values in this form field?” This approach necessitates an interruption, but doesn’t require any expertise in the software’s implementation. Another approach, and frankly, a better approach, is to take a peek at the form field’s implementation, to see that the field validates on a regular expression that unambiguously describes the accepted values. The documentation can more closely adhere to the reality of the software, and less developer time is spent recapitulating the source code.

So, just as Baker pointed out, a writer SME can consume less of a developer’s time trying to understand software. That’s not to say code is the whole of understanding software. SMEs must be called upon to share intentions and expectations that code doesn’t or can’t capture (in the example case, the implementation may not have been the intended one), but the importance of code is hard to overstate. A writer with subject matter expertise can work without relying solely upon the intercession of other SMEs. A writer-programmer can go directly to the source of truth about the system.

On Monday night, I went to IKEA. Personally, I like IKEA. The furniture looks nice enough and I feel as though the money I spend there is proportional to the value I receive from having IKEA products in my home. And I like that I can leave without ever having dealt with a salesperson. Yet practically no mention of IKEA may go by without eliciting at least one of the two chief complaints about IKEA:

1. IKEA stores are like mazes and easy to get lost in.
2. IKEA assembly instructions are difficult to understand and to complete.

I wonder about where these complaints come from, however, because I’ve never been lost in IKEA (though I admit that IKEA generally permits only movement forward and backward, but almost never left or right). And I’ve never had any trouble following IKEA’s assembly instructions, even when following the directions took far longer than I guessed. Indeed, compared to other flat pack furniture, IKEA’s instructions are a model of excellence when it comes to realistic scale and orientation.

So having heard these complaints about IKEA for so long, I think the complaints might actually reveal less about IKEA, and more about the people complaining. The people complaining have a harder time thinking about movement through space and time. IKEA’s buildings could almost certainly be designed to be less demanding of spatial reasoning skills.  But surely there’s no business case for making the directions any more demanding than necessary. Instead, I suspect that IKEA’s directions are a minimally demanding example of the wordless flat pack assembly directions genre. It leads to an awkward conclusion: the people complaining of being unable to complete IKEA’s instructions shouldn’t really be trying.

In some ways, the problem of users being unqualified to follow some directions is routine. Writers often take steps to tell their readers the prerequisites for some task. Some will do so explicitly, with a list or a qualifying statement (“To complete this tutorial, you’ll need…”). Others will do so more implicitly, describing a task in terms that only an audience member meeting the prerequisites would understand or recognize. In any case, it’s a solved problem, since, in most cases, the prerequisites are acquirable. You simply ask your user to come back later.

In the case of IKEA’s product, however, the prerequisite skill of translating two-dimensional images into a three-dimensional object isn’t exactly something you can go out and learn in an afternoon. As much as it would amuse me to see it, IKEA can’t exactly prepend a step to their directions requiring users to first spend a few years playing with LEGO bricks. It’s a tough thing to ask. But remaining silent on the matter isn’t doing their brand any favors, as their instructions’ reputation so clearly indicates. Sometimes you have to be honest with your audience, even if that means telling them that they’re out of their depth.

A few months ago I submitted this pull request to the Django project to fix an awkward example in the project’s developer documentation. Originally, a little piece of the coding style document presented an example of a model (simply put, an object representing some data) that provided a set of choices, a list of accepted values for some data in the model. The list of accepted values were male and female only. The portion of the document was meant only to demonstrate how a set of choices was to appear in the source code, not how to collect gender data. I proposed a tiny change (that was accepted) to render the example genderless, with a set of choices up and down (for, say, storing elevator usage statistics or something).

I wrote the revised example on the basis of one of the earliest lessons I had in technical writing. My first technical writing class in college was a service learning course. The course was something of an eye-opener, showing me challenges that are often invisible to a wealthy, healthy, able-bodied, hetero white guy. My classmates and I made a basic website for a Ryan White CARE Act consortium. The Ryan White CARE Act provides funding to help pay for the care of people living with HIV/AIDS. Some of the funding is supposed to be spent with the recommendation of local consortia, made up of people in communities where the money is spent, including people who have HIV infection. At the start of the project, we did some introductory audience analysis, and surveyed members of the consortium about their needs and expectations.

Our first draft of the survey for the members included some seemingly innocuous demographic questions about the respondents’ city, age, and, yes, gender. Like the Django example, we supplied two choices: male and female. Luckily, before we distributed the survey to the consortium’s members, we learned how clumsy and insensitive our question was. Asking about someone’s gender is more challenging than you might guess. It presented two problems: the first being the accuracy of choices available to respondents, and the second being the message to respondents who aren’t represented by the available choices.

The first problem was that respondents who wanted to answer a question about their gender might have found that their preferred choice was not an option. So, for instance, a respondent might have preferred to choose “intersex,” but the option was not presented. The respondent would have been forced to choose to answer less accurately than desired, or leave the question unanswered. Moreover, what constituted an accurate response may have also been unclear, as many people are stuck with a discrepancy between their gender identity and their legal identification (e.g., on a driver’s license or birth certificate). In our draft survey, all questions were optional, but the problem would’ve been exacerbated if we required responses.

The second problem is more troubling. By not presenting a broad range of choices, we ran the risk of alienating would-be respondents. Given the stigmatization associated with HIV, respondents would’ve been rightly suspicious of a survey that did not afford them the opportunity to represent themselves. By offering only male and female as choices, it needlessly implied exclusion to those who don’t identify with those options. Choices like that draw undue and unfair attention to some respondents’ gender identity more than others.

In the end, my classmates and I were faced with a choice of our own: make the question open-ended or eliminate it. We came to the conclusion that the gender breakdown of our audience didn’t matter much to our writing process, so we chose to drop it. When I came across that example in the Django documentation, I made a similar consideration. Since the point of the example code was to show a limited set of choices, it wouldn’t be possible to create an inclusive version, so I removed the need for it. (Of course, credit to Adrian Holvalty of the Django project who accepted the pull request almost entirely without comment.)

It’s not a very costly edit. There’s no loss of clarity and it’s just a few bytes difference. But if you’re asking for help, whether it’s to code with a certain style for your framework or to answer a few questions for a website, it pays to include—or at least not exclude—the people you’re asking. Small incremental changes like these are an important step in reaching the fullest extent of your audience.

Feedback is probably the most maddening thing about being a writer. In contrast to programming, for example, in writing it’s incredibly difficult to get feedback rapidly. I can run a test suite on my code every minute if I want to, but I have to find a real, live human to read over my documentation, every time.

And even if I can wring some feedback out of somebody, what I get back can be all over the place. Some feedback gives me insight and motivation, while some feedback makes me angry and wastes my time. So I try to evaluate the feedback I receive in relationship to the meaningful change it does or does not support. Then I can choose whether to embrace, reject, defer, or ignore it.

Thus, the feedback matrix:

The horizontal axis is usefulness, whether the feedback can be acted upon to make actual change to the outcome of a project. Feedback is useless when it cannot be acted upon. Feedback is actionable when doing something doesn’t run afoul of some constraint, like project scope, legal requirements, or some aesthetic principle.

The veritcal axis is significance, whether the feedback concerns some necessary, important, or memorable aspect of a project. Feedback is insignificant, or trivial, when it concerns portions of a project that are little valued, low visibility, or inconsequential.

So, placed on both axes, feedback can be assessed as falling into one of the four quadrants:

A few months ago, I received an email from a respected company about a security problem relating to their service. I wrote out a long take down of the message, critiquing it line by line, highlighting each of its various flaws. It was a serious problem communicated without serious care. But I never posted the critique because it was plain that the author wrote and sent the message earnestly, albeit incompetently.

It’s unfair to go after a single draft, since a bad draft is a routine byproduct of the writing process. As long as bad drafts are a byproduct of the process and not the product itself, they are unworthy of our attention. When a bad draft is unleashed on unsuspecting audience, it’s not bad writing, but bad process. It represents the failure to involve a competent editor prior to publication.

There are plenty of reasons and excuses for not having an editor as a part of the process, like costs and deadlines and many others I’m sure you’re quite capable of conjuring up. But there are good reasons to engage the services of an editor. Today I’d like to remind you of five:

1. Your brain will overlook errors.¹

It’s easy to pretend that one can fully self-edit. Though there are tricks to improving the quality of writing without an editor’s attention, they’re no substitute for the real thing. When you read your work, you will understand each part and how it contributes to the whole. Only the perspective of other readers can demonstrate whether your understanding can be recreated by others. An editor’s eyes will see what yours do not.

2. Everyone’s a critic.

Few if any readers will check your math or technical details, but many are quick to call out errors in spelling, grammar, and usage. In a special case of Parkinson’s law of triviality, readers will gravitate toward small, easily recognized mistakes and tell you all about them. This lowers the esteem of the author and the work in the eyes of the audience. A good editor can protect an author from an avoidable loss of credibility.

3. Your writing’s worse than you think.

When you think you can get by without an editor, you’ve overestimated your writing ability. The relationship between confidence and writing skill are inversely related. Because basic writing skills are widely taught (see: everyone’s a critic), there’s a common assumption that writing is easy, or at least easily mastered. Editorial input normalizes perceptions to reality. An honest editor can replace overconfidence about your writing with real confidence.

4. Good ideas get lost in bad execution.

Deficient writing does not imply deficient thought. Expressing ideas in words is distinct from coming up with the ideas in the first place. Writing left unedited can hide considerable thought behind it. A competent editor can help you express yourself fully and prevent you from burying your own lead.

5. Errors are costly.

Deciding how much to trust and rely on a person or business hinges, at least in part, on the things they say. An error in advertising copy or an important security message can easily change perceptions. Personally, I’ve skipped buying a service on the basis of problematic prose.² An editor can prevent errors that lose sales or customer esteem.

Having an editor around can be the difference between successful and failed communications. Editors find all kinds of errors, not just spelling and grammatical mistakes. An editor can ask important questions about the meaning, intent, and effect of your writing that you cannot. In the extreme case, an editor can spare you embarrassment and distress. During Hurricane Sandy, some companies produced copywriting widely regarded as insensitive. Had someone played the part of editor and asked how such messages would be received, they may never have seen light of day. So the next time you, or your blog, or your business is about to publish something without the benefit of the editorial process, you may want to consider whether you can afford it.

As you may have noticed, today’s post is shorter and later than usual, and that’s partly because of some distractions related to that hurricane you’ve probably heard about. Over the weekend, I took a little time out of preparing for the oncoming storm to write a single-serving web application called powerup.

A single-serving site is a web site that’s focused on doing just one thing, to the exclusion of all others. One of my favorite examples is downforeveryoneorjustme.com, which does what it says on the tin: it tells you if a website is down for everyone, or just you. I made my single-serving site to answer a simple question: is the power on at home?

After July’s derecho, my home was without power for five days. So spending time in air-conditioned places became a top priority, but finding out whether the power had come back on at home became a chore. When Hurricane Sandy was likely to pass through my area, I expected to be without power again, so I whipped up this application which tells me just one thing: if the power is on. More technically, it tells me whether my router at home can connect to an outside server, but for my purposes they’re basically the same question.

Now, I didn’t actually lose power (a surprising development), so powerup didn’t turn out to as useful as I imagined it would. But finding an irreducible unit of information, below which is meaningless and above which is superfluous, is a satisfying and powerful exercise.

Conceptually, a single-serving site is the opposite of comprehensive. Rather than providing as much information as possible, a single serving-site provides as close to the minimum useful unit of information as possible. In the case of sites like mine or isitchristmas.com, the minimum useful unit of information is a solitary bit: on or off, yes or no. For a site like How Many People Are In Space Right Now?, it’s an integer.

Irreducibility shouldn’t be the only objective when trying to share information with people, but that irreducible unit of information is a thing worth having. It can be the nucleus at the center of a larger application, presentation, or document. While a single serving site may not be a practical approach in all or even most cases, thinking about what the single serving site of your topic would look like isn’t a bad place to begin.

In college, a major emphasis of my technical writing classes was focusing on the audience. Specifically, those courses taught a skill called audience analysis. Using audience analysis, a writer begins the process of creating documentation by studying the audience and understanding their needs, desires, and expectations. Audience analysis, idealized, works something like this:

Suppose a writer trained in audience analysis is asked to create a tutorial for some software application. She might begin by looking at the members of her audience, identifying tasks the people in that audience want to achieve, and recognizing what skills and limitations they already have. The writer might learn that a subset of the audience has visual impairments and requires additional accessibility affordances. Or she might learn that the audience is made up of expert Linux users who prefer instructions for the command-line interface instead of the graphical interface. Whatever she learns, she uses it to produce documentation tailored to her audience. And, hopefully, that audience finds her documentation to be a delightful, helpful tool in completing the tasks they set out to achieve. Then there are high fives all around.

At the time I was learning this skill, I supposed, somewhat cynically, that there was a sort of pleasant fiction to the instruction, in that the skill wasn’t meant to be directed toward the ostensible audience of technical communications. Rather, I thought the purpose was to do audience analysis on the person who wants the work done: a professor, a boss, or a client. It would be rational to value my client’s appreciation for my deliverables more than my audience‘s appreciation for my deliverables. The incentives would be arranged such that my success is tied mostly to what a client, not an audience, thinks of my work.

And now that I’ve put a few years between me and my introduction to audience analysis, I’ve found that though my cynicism was misplaced, my estimation of the incentives was correct. But I was wrong in supposing there was a dichotomy between applying audience analysis to the ostensible audience or the paying client. There just happens to be a larger number of audiences than I was trained to expect. In practice, there’s an official outside audience of customers and users, for whom a writer ostensibly produces documentation. And then there’s an unofficial, inside audience of check-cutters.

The desired deliverable for the outside audience is likely to be a manual or screencast or some other thing that will instruct them in some task. Meanwhile, the desired deliverable to the inside audience is actually a kind of performance. If the interests of my audience and my client are perfectly aligned, the performance is creating the deliverable. But if not, it’s not really a problem: the interests don’t actually compete.

Suppose the client’s interest is in lowering support costs. The desired performance is doing things, creating deliverables, that lower support costs (in as much as those costs can be identified). It doesn’t necessarily follow that writing for the outside audience is a path to successfully completing that performance. The work that needs to be done may be improving searchability (e.g., SEO), deleting cruft, or writing primarily for the benefit of an internal audience (e.g., support team members). Some “real” audience ultimately gets a deliverable, but the client gets the performance they need.

And this approach fits with the idea that many, many technical writers have been emphasizing for so long: making the business case for your work. It’s just that this way, we’ve arrived at the business case by reverse. Rather than looking for ways to justify existing work to the people who write checks, it’s about looking for ways to work directly toward the satisfaction of the people who write checks. Or to put it another way, the audience analysis skills that are the core of technical communication education and the core competency of technical communicators is a skill that can be handily deployed to satisfy the needs of the audiences inside and out.