I don’t envy the work of developers and system administrators who are responsible for the security of a software system. For starters, it’s a hard thing to think about conceptually. You have to ask yourself, again and again, how might someone wreck all the stuff I’ve accomplished? Moreover, security is just plain hard to do. Software security is one person, team, or organization against a wild world of software exploitation. In a fight like that, the discovery of a serious security vulnerability isn’t avoidable, it’s inevitable.

So it’s not surprising that 2010 had several high profile security incidents. The two that stand out in my mind are Firesheep and Gawker Media’s security compromise. Firesheep, a Firefox extension released in October, demonstrated just how easy it is to hijack someone’s browser session over public wifi. In December, more than a million of Gawker Media’s users’ passwords were publicly distributed. These two incidents stand out not only for their recency, but also in the way that they demonstrated that security is difficult to get right and difficult to explain when things go wrong. Both incidents illustrated that users themselves have very little control over how secure they are on the web. Moreover, each incident illustrated that many critical components in security are frequently arcane and complex.

In the case of Firesheep, many people learned that sessions which aren’t protected by SSL—that little padlock in your browser window—are vulnerable to attack over public, unencrypted wifi. With Firesheep installed, someone can sit down in Starbucks and, within minutes, snoop Facebook accounts, webmail, and more. It’s a difficult problem to fix, as very few non-login pages are served with SSL enabled and the cost of doing so can be high. But Firesheep also exposed another difficulty: it’s incredibly hard to teach someone how to know whether their session is secure or not. There are several layers: transport, browser, and network, which must be secured. I’ve forgotten the risks while using public wifi; how do you teach a less technical audience to do as well or better? Take a look at this account of an attempt to actively warn users of the risks by hijacking sessions. If that doesn’t work, what would?

Likewise, consider that Gawker Media’s user account data was illicitly accessed and distributed. A huge number of passwords and email addresses were revealed to the world. Though the passwords were not stored in cleartext, Gawker Media used a particular method of storing passwords—a DES hash, for those interested—which made it possible for many of the passwords to be trivially deciphered. If Gawker Media’s users with exposed passwords reused their username and password combination elsewhere, those accounts could potentially be compromised as well. Had Gawker Media used a different method to store passwords, that may not have been the case. Gawker Media ended up preparing a 26-question FAQ to help their users not only understand what the effects of the compromise were, but also what to do about it.

In both cases, users were faced with a problem largely out of their control, but with potentially frustrating and costly effects. Those responsible for the security of Facebook, Gmail, and Gawker Media had headaches, but so too did those responsible for explaining what had happened. And I’m not sure anyone did an entirely satisfactory job of it. I think, more and more, the problem of security isn’t just the problem of security. It’s also a problem of helping people understand what security means and what it means to not have it.

Last week, I discussed how style guides are a help and hindrance. In this follow-up, it’s time to take a look at how style guides might adapt to new, web-based publishing models.

During the summer of 2007, I worked at Google as technical writer intern. Toward the end of my internship, I attended an all-day meeting of nearly all the technical writers at Google. One of the writers brought her dog to the meeting. At the merest mention of the possibility of a Google-wide style guide, the dog groaned. Loudly. Even the animals at Google had come to embrace the culture there of openly resenting style guides. There was some discussion—despite the dog’s protests—but little enthusiasm for the idea. Google seems to get by without an absolutely consistent voice across their various bits and pieces of documentation.

On the other hand, during the course of my internship project, my mentor at Google and I developed an informal style guide to help us coordinate our work on Google Desktop. It wasn’t an exhaustive document like the AP Style Guide or the Chicago Manual of Style; it just covered a handful of possible inconsistencies we had run into. It wasn’t hard to maintain and helped avoid some unnecessary editorial effort. So why did it work for us specifically, when Google’s technical writers rejected the idea in general?

Google is in a currently unusual situation when it comes to style guides. Google, in contrast to many other large software companies, doesn’t make use of centralized technical writing departments. Many large software companies either outsource or have teams of technical writers working together to serve as an internal clearinghouse for docs. At Google, technical writers usually work as a part of a particular product, frequently as that product’s only writer.

Moreover, what Google publishes more often than not are single web pages that address some limited issue, not monolithic manuals. I’m all but certain Google has never distributed a printed manual (though it’s tough to prove a negative). Such a work and publishing model is suited to an individual author owning a collection of docs, rather than spreading the work of that collection to several writers.

In that context, the path to a successful style guide becomes more clear. In such a content creation and distribution model, specificity becomes a key word in creating a style guide. When few authors are focused on a limited area (like a particular product, system, or process), a style guide need not become a monolithic document to advise on every possible writing decision. Instead, those authors that take ownership of some documentation can craft a product-, system-, or process-specific style guide. Writers can use a style guide of a size and character which is congruent with the size and character of the documentation they’re producing.

I think we need a new mantra for software libraries, especially in the Open Source world, that applies to entire projects or features of individuals libraries:

Docs or it doesn’t exist.

—Docs or it doesn’t exist by Luke Plant

An interesting rant that compares releasing a software library without documentation to a public nuisance, like a refrigerator left out on the curb.

This post is the first of two parts on the frustrations and the future place of style guides.

I hate all style guides. Well, except mine.

From afar, a style guide is a compelling idea. With a style guide, you could coordinate the efforts of several writers. A group could work, simultaneously and mostly autonomously, on the same document while still giving the impression of a single voice. Multiple writers could produce a consistent, uniform whole instead of a schizophrenic mess. That said, I still hate style guides.

I’ve come to suspect that this is a thought most, if not all, technical writers have thought at some point or another. Many are unlikely to admit to it. There are two main reasons many writers do not acknowledge their problems with style guides: many a technical writer’s job performance is judged on the basis of how fastidiously they adhere to the local style guide and, well, their style guide is special.

If a writer comes up with her own style guide—or she has the authority to create and modify the house style guide—a style guide is just an explicit description of how that author would have written in isolation. It’s a case of “paving the cowpaths.” While writing the style guide may take time, the style guide itself doesn’t add any work to the process of writing documentation. It just tells others what an existing process inside the writer’s head looks like.

On the other hand, a style guide out of the control of a writer is a recipe for additional, tedious effort. A sufficiently complicated style guide adds considerable overhead to the writing process; not only must a writer articulate an idea in words, but it must be checked against the arbitrary rules of a style guide.

And all style guides are arbitrary. What’s the difference between e-mail and email? Almost every reader is going to recognize e-mail and email as referring to the same concept. Choosing one or the other is entirely arbitrary; a collection of such arbitrary choices is called a style guide. The arbitrariness of a style guide is where the mental overhead of a style guide resides. Each writer’s stylistic choices will be different than all other’s; bending to a particular style guide can be a tiresome exercise. And who wants to do that?

Perhaps, in the future, we’ll have software to understand and monitor documentation for style guide violations, like a sort of natural language compiler. But for now, I’m confessing: I hate style guides, except mine. But I’ll use one anyway.

A foolish consistency is the hobgoblin of little minds, adored by little statesmen and philosophers and divines.

—Ralph Waldo Emerson

From the accepted answer to What are some better alternatives to help files? on Stack Overflow:

If you have to write a help [file] you have already failed in your program design. Have you ever seen a help menu on your iphone or on facebook? Millions of average Joe people use them every day without problem.

I’ve heard a lot of variations of this sentiment, like, good software doesn’t need directions and manuals are bandaids for bad software. I don’t know where this bone-headed trope came from, but the idea that good user interfaces don’t require documentation is just not rational.

Even if we take at face value the idea that prominent devices and software, like the iPhone and Facebook, represent the pinnacle in interaction design—although many find that is not the case—it’s incredibly rare for such products to be shipped without some method of instructing users. For example, iPhone 4 ships with the cleverly-titled Finger Tips [PDF] getting started guide to show new iPhone owners how to turn the device on and off and how to make phone calls. Likewise, Facebook offers a vast help site to answer questions ranging from How do I log in to my Facebook account? to How do I create Facebook Ads?. If such great accomplishments in user interaction are still shipping help and manuals, are they wasting time, effort, and money on a signature of bad design?

In reality, all but the most simple tools require instruction in their use. And I’m not even entirely sure about that; even the earliest tools, like pointy sticks and clubs, push the limits of instruction-less use. Carefully-designed tools often stump otherwise technology-competent people.

For example, the first time I used an Apple iPad, I could not immediately turn the device on. My initial guess about how to turn on the device based on my experience with another Apple iDevice—a classic iPod—failed: in contrast to the iPod, the button on the face of iPad does not wake the device. Likewise, my second attempt to wake the device failed too: the apparent black button on the right edge is actually a volume toggle. The actual power button is on the top edge of the device and, like all of the buttons on the iPad, is unmarked. Without some well-timed pointing on the part of the device’s owner, I would have given up without getting even that far. Other features of the iPad, like pinch-to-zoom gestures, are even harder to deliberately discover (if you even knew they existed).

I’m not saying a help file, printed manual, or video tutorial is the only way to impart usage information. For instance, some video games do an excellent job doing interactive training of which the player is nearly unaware (Half-Life 2: Episode One’s in-game commentary mode has a brilliant explanation of how this training can be put together). And certainly, if all other things are equal, better interfaces will require less instruction. But I remain totally unconvinced that good user interfaces can be made without some kind of instruction. Even the 2.5-year-old iPad user relies on the implicit instruction of seeing and using the similar iPhone.

Instead, I offer this alternative to idea that good software doesn’t need documentation: if you haven’t considered how you’re going to teach the use of your software, you have already failed to create a usable tool.

There are several tools out there that produce documentation based on comments in source code. They’re typically tailored to a specific programming language. For example, Java has Javadoc. Ruby has RDoc. Python has Epydoc. Almost every language has one and they’re almost always popular. From a developer’s standpoint they’re very compelling: you get to describe all of the functions, classes, methods, and things in the same source code files you work with all day. New documentation gets generated along side the latest build of the software itself. If you’re writing comments in your code anyway, it’s practically free documentation. Except for one thing: to describe the output of these tools as documentation is perhaps overstating the case.

First, let’s take a look at what actually comes out of one of these tools. Here’s a screenshot from the Epydoc output for Paramiko, a library for Python for working with Secure Shell connections:

The output from Javadoc is quite similar, while RDoc’s primary difference is putting the navigation frame along the top, rather than the left. Otherwise, all of these tools output something more or less the same: a bunch of pages which help show the various functions, classes, and methods available in package.

But now look at the source where this stuff actually comes from:

The difference here is minimal. The body of the methods, for example, are hidden in the Epydoc output (though accessible through the source code links), but we still see the method signatures and the first sentence from the docstring in the source (in other languages, an equivalent comment block would serve the same purpose).

And this brings me to my hesitation at calling the output of these tools documentation. These “documents” are handy and perhaps the highest ratio effort-to-usefulness things a package maintainer can do for her users, but they’re not so different from the source code itself.

So instead of thinking of these tools as documentation generators, I’ve come to think of Epydoc and Javadoc and RDoc as code skimmers. Instead of getting a human-organized corpus of for-human-readers-only material, what I’m really getting is the source code’s Greatest Hits. These sorta-docs contain the top of class definitions, method signatures, and comments: the things in the source code I would turn to first, before almost everything else, to try to understand how the software works. These documentation generators do an excellent job at producing materials that show the hows of software, even if they’re not accompanied by explanatory whys.

I don’t mean to cheapen the good that Javadoc and similar tools do by thinking of them as code skimmers. Rather, under such terms, the possibilities are broadened. Perhaps the descendants of these tools will serve as intelligent code viewers, interactively revealing and obscuring beautifully formatted source code for the benefit of human readers. In some respect these future code skimmers are already on their way in the form of integrated bug trackers like Trac, GitHub, and BitBucket.

(For a different—and much less generous—view of documentation generators, check out Writing great documentation: What to write by Jacob Kaplan-Moss.)

In a lot of systems, there are relationships in which one computer, device, or process acts in a supervisory or managerial role with respect to other, similar, devices. Oftentimes, these relationships are said to be a master/slave configuration. My first encounter with this terminology was when, as a kid, I added a second hard drive to the family computer. One drive, the original, was configured as the primary, master drive and the shiny new 1GB drive was configured as the slave.

I hadn’t thought much about the phrase in a long time, until I saw Jacob Kaplan-Moss’s recent series about using Buildbot to run the testing suite for the Django web framework:

We can’t just run a farm of Linux buildslaves running Python 2.6 and SQLite. Since slaves are heterogeneous, the build system needs to be highly targeted. We can’t treat each build slave identically, but we’ll need to target certain types of tests to the slaves that support ‘em.

In Jacob Kaplan-Moss’s case, there’s a computer in charge of a bunch of other (virtual) computers that are running a really staggering volume of tests for the Django project. Slaves isn’t an unexpected term to see here, but the repeated use got to me a little, ultimately leading to this declaration on my notepad: Master/slave has got to go. And you should avoid it in your writing, if you can get away with it.

The most obvious case for avoiding master/slave is that it is offensive because the metaphor diminishes actually slavery. Slavery is a horror involving compulsory labor and sex; to use it to refer to something as benign as a couple of hard drives is a misstep.

But I can imagine voices asking, “Isn’t that just political correctness run amok?” and “We’ve used this phrase forever; why stop now?” so I think it’s only fair to offer a more pragmatic case against the master/slave idiom.

Even if you don’t buy into political correctness per se, it’s still in an author’s best interest to avoid distracting the audience with references totally unrelated to the current topic. While you’re busy explaining a database replication scheme, you can lose your audience to disturbing thoughts about the Atlantic slave trade or the Sudanese Civil War. This becomes increasingly likely as the international character of your audience increases: while the current practice of slavery is almost unheard of in wealthy places like the United States, Canada, and Western Europe, it’s prevalence and broader societal impact is much greater elsewhere, particularly in Africa.

Moreover, the master/slave metaphor is often harder to follow than being specific to your particular system. In Jacob Kaplan-Moss’s article, the master/slave idiom is used to describe the relationship between the Buildbot server (the master) and the various test running machines (the slaves). Rather than obfuscating with the word slaves, it might have been clearer to say testers, test runners, test machines or test VMs. They’re not that much longer to type, but they rely less heavily on context to understand.

To think of a system in terms of master and slaves is fairly common in technology, so I don’t mean to pick on Jacob Kaplan-Moss or anybody else who uses the phrase in their writing and documentation. It’s not deliberately offensive and many of your audience members won’t give it a second thought. But for those that do give it a second thought and for those that are slowed down by the abstraction, it’s a distinct disservice and it should be avoided.

Note: If you’re reading Hack Writing via the RSS feed, you may need to resubscribe. The feed now contains the full text of each article, instead of an excerpt; some RSS readers (namely, Google Reader) have not been displaying the full text without resubscribing.

After Assuming the worst, I received several comments from readers asking, more or less, “What’s an API?” In this post, I hope to satisfactorily answer the question and to give you a sense of the documentation issues that surround APIs.

API stands for “application programming interface.” In practice, it’s the way one piece of software communicates with another piece of software. Although you might interact with a piece of software through a user interface (i.e., the part of an application on your computer, a web page in your browser, or an app on your phone that you type, click, or tap on), software typically communicate with each other by way of APIs.

For example, suppose you love Twitter, but you don’t want to go to Twitter’s website every time you update. Instead, you want a program on your computer to post to Twitter for you (known as Twitter “client”). It’s possible to write a program that, behind the scenes, goes to a web page, submits a form, and handles the response, but it’s a cumbersome and fragile proposition. What if the layout of the page changes? What happens if the wording of a confirmation message changes? How many clicks and keystrokes must be passed along? There has to be a better way.

And there is. Many web services and software packages provide an API. In the most general sense, an API is a specification. An API describes how other software can interact with it directly, bypassing the user’s interface. Frequently, APIs take the form of programming language bindings and software libraries that can more tightly couple two (or more) software programs. In our example, Twitter defines an HTTP API. Software that uses the Twitter API sends Twitter a specifically formatted chunk of text over the Web to ask for data. Practically anything that can be done by way of the Twitter website can be done with Twitter’s API: listing tweets, showing user details, or posting new updates.

For many software developers, particularly for those on the web, an API’s documentation may as well be the sole representation of the API, aside from directly interacting with it. Most web services are closed source, which is to say that the implementation of the service is not publicly available. Thus, for software developers who work with web services, the API documentation is the only official representation of the API they have. For a developer, it’s often the case that a discrepancy between an API’s documented function and actual use constitutes a bug in the API, whereas the maintainers of the API might regard it as a bug with the documentation. And ultimately, it’s the potential for discrepancies which introduce the challenge of creating high-quality API documentation.

API and documentation discrepancies can come from various sources, including:

• Various versions of the API
• Different formats for sending and receiving data (e.g., XML or JSON)
• Varying platforms (e.g., Mac versus PC or Desktop versus Mobile)
• New features
• Deprecated features

Each possible point of contention between documentation and implementation poses a question to an API documentation author: how do I describe to users how and under what circumstances this thing can or should be used? Moreover, it behooves the author to be accurate and clear; getting it wrong or inadvertently misleading readers can be as detrimental as an outright bug in the API’s implementation.

When it comes to API documentation, the stakes are high. An API’s popularity frequently depends on the documentation appropriately and accurately describing the API to developers who may use it. While a web service might have a powerful and useful API, if developers can’t understand what it does, it won’t be used. And that can cost an organization time, customers, or even overall success.

"What's important?" by Valerie Everett (used under a CC-BY-SA license).

Too often I see the dreaded Important Noun. I didn’t notice this effect until, when I started with WebFaction, nobody referred to the custom control panel as the Control Panel and no one insisted that I do that in the documentation. It’s not the Holy Grail, I was told. It makes perfect sense of course—what’s so proper about a control panel?—but after seeing so many products insist that their Ordinary Thing was Special, I assumed it was standard practice.

Consider an example from a Stack Overflow question I answered a while back, How should important terms be emphasized in documentation? (emphasis mine):

Software will often introduce and formalize concepts that may have ambiguous definitions in the real world. For example, in an attendance tracking system, an Occurrence refers to an Excused Absence, an Unexcused Absence, or a Tardy.

Traditionally, capitalization is a fun thing reserved to help distinguish the first character in a sentence or for the dignity of proper nouns. Why is It showing Up every Other word In technical Documentation?

Sometimes a phrase is just a phrase, even though its referring to something important to the author. With the exception of “Occurrence,” I don’t think those nouns are particularly proper. “Excused absence” and “approval form” are descriptive as ordinary noun phrases; if I came across these in their capitalized form, I think I’d wonder if they’re oblique references or outright euphemisms.

“Occurrence” is problematic, however. Usually, occurrence means “something that occurs,” which is vague to the point of meaninglessness. In this case, the author has the opportunity to be much more descriptive without repurposing an existing word. Which points to the problem rather squarely: each observed case of the Capitalization syndrome represents a missed opportunity. Rather than being more descriptive within the current lexicon, the author decides that no existing words will do. The author misappropriates an existing word and lets everyone know how special this “new” word is with the liberal application of Capital Letters.

Of course, that’s not to say I’m against proper nouns. I’m all for giving things distinctive names. Go nuts with CamelCase, even. I don’t care. But lay off my ordinary nouns. Can’t I just be tardy without being Tardy?