This is the second article in the Use of Language series. It is worth reading them in sequence:
1) Chrome Browser: A Novel Approach to Language
2) SQL Response: Choosing Our Words Carefully
3) SQL Response: Does Everything Need a Name?

Historically, the profession of "technical author" emerged from the nascent aerospace and technology industries following the war, and brought with it a military-style rigidity of approach to standards and formality. But documenting (and putting words into) software in 2008 is very different from documenting the wiring of a cockpit in a fighter jet in 1952; perhaps we need to relax more… and be more like Google.

When you’re creating a new application, and where it is crucial to make it as simple to learn and use as possible, you can take nothing for granted. One of the most important tasks that you face is to make the language of the application as obvious, intuitive and accessible as possible. Even complex activities can be made simple by a careful choice of words. As the range of software users increases, this challenge only becomes more crucial.

The ubiquity of the internet has turned almost the entire population of planet Earth into software users; software has insinuated itself into all our lives, so perhaps its language needs to be more like the language of everyday life, and less like arcane techno babble.

At the same time, however, we still need to be enormously careful about eradicating naming issues that baffle users and sabotage otherwise great products. We still need to avoid inconsistencies, regionally specific idioms, and ambiguities.

Like the reasonable people we are, our approach to this issue is to strike a balance. We want to be cool and accessible, but also sensible, consistent and usable. While Google are using phrases like "Under the Hood", in the end they probably wouldn't pass muster at Red Gate.

"I have no name…. what shall I call thee?"

As a technical author, it's my responsibility to give things sensible names in the application, and I have to contend with a host of conflicting considerations.

“
Fundamentally, names
have to be comprehensible
to their audience;
knowing the likely
users of your application
is critical.
                       ”

Naming features and dialogs can be like naming your new-born son or daughter; everyone has an idea or suggestion. For example, developers tend to refer to things by the names that they've used for methods and interfaces in their code. If we're not careful, these names creep into the GUI and, not surprisingly, some of them are less than meaningful to normal humans.

Meanwhile, marketing people tend to ignore your names and write about what they think is most likely to sell the product, using buzzwords that they know customers find desirable, and search for.

Fundamentally, names have to be comprehensible to their audience; knowing the likely users of your application is critical. For example, at the moment I'm working on SQL Response, and it's a tool for DBAs. I can therefore assume that they understand terms like "cluster", "deadlock", "credentials" and so on.

Some names are well-established and therefore comprehensible to all. "Cut", "Paste", "Print", "Delete", "Save" etc – by now these terms have entered the common lexicon. It's instructive to remember, however, that there was a time when each of these words was first used in an application, and that someone, somewhere, must have spent hours agonising over whether "Paste" was in fact a sensible word for taking data from one place to another, while (optionally) leaving it in its original location. I'm not convinced they did a great job - in the real world, "paste" doesn't really mean any such thing; it's more to do with adhesive properties, like sticking up wallpaper.

Names must also be used consistently. Users are bamboozled by options that do one thing in one place, and something quite different elsewhere in the same application, or even within another application from the same company. If we refer to a "project" in one place, we must mean exactly the same thing when we use the same word elsewhere. No freewheeling anarchy here.

Case-study: SQL Response

At the moment, I'm working on SQL Response, the very-soon-to-be-released new SQL Server monitoring tool for DBAs from Red Gate.

I have a confession to make first: I don't like the product name. I argued, unsuccessfully in the end, that you would expect a tool called "SQL Response" to enable you to respond to SQL Server problems in some way. But the interactive element of fixing the problems raised by SQL Response proved too difficult to implement in the first version and so was dropped very early on in the development cycle. So, SQL Response does a lot of monitoring and alerting, but no responding.

I suppose you could argue that "Response" means that SQL Response 'responds' to problems by alerting you to them in the first place, but that's stretching the meaning of the word to breaking point.

Unfortunately, the product name is the only name (visible to end users) in the entire project that doesn't come within my purview.

SQL Response is a brand-new tool for Red Gate, and as such came into the world nameless and innocent. My first task was to establish a terminology document listing the correct names to be used for each main aspect of the application. Here are some of the issues I encountered.

Incidents or alerts?

“
"There's been an incident".
It sounds serious. The
sort of thing a TV
detective would say
following a murder...
                       ”

When we were developing the first BETA version of SQL Response, quite a while ago now (in fact further in the past than any of us on the project would care to admit) we only ever referred to "incidents" in SQL Response.

An "incident" was anything that SQL Response identified as a potential problem on any of your monitored SQL Servers - a job failure, a long running query, low disk space, that sort of thing.

I was never hugely enamoured with this word, mainly because its connotations were too suggestive. "There's been an incident". It sounds serious. The sort of thing a TV detective would say following a murder, or a mysterious blaze at a disused warehouse. Also, because SQL Response has told you about something, it doesn't necessarily follow that what's happening is an "incident". It may be something you don't care about, or need to reconfigure the tool to ignore. It's more like a warning, after which you may or may not choose to take action. If the traffic light is red, then you shouldn't cross the road. But if it's 4am, and you can see for 500 meters in both directions, it isn't dangerous.

We now have alerts in SQL Response. They are "raised" (not "triggered"). They have Low, Medium and High "levels" (not "priorities") ". They can be "cleared" (not "closed"). They each have "configuration" (not "criteria").

So far, so good. Time to ask a difficult question – would it really have mattered if we'd chosen the alternative terms?

"Close a triggered Low priority incident."

or

"Clear a raised Low level alert."

The answer is – probably not. Users of SQL Response would quickly figure out what the action meant and, if the terms were used consistently, would not have a problem. But that's not to say we didn't spend time evaluating the relative merits of each one of those terms. "Priority" has connotations that may not match how a user wants to make use of our more neutral "levels". "Closing" an alert doesn't really do what you may expect, as the alert is still visible.

Is a recommendation an alert?

We did hit a problem, however. SQL Response raises two types of "alert". The standard type of alert, and also recommendations.

Recommendations differ in some subtle ways from alerts (for an example they cannot be cleared) but in other ways are identical. It turns out that many of the settings in SQL Response can apply to both alerts and recommendations.

What would help us is an umbrella term that means "alerts and recommendations". The best we can manage is "item", but this is semantically rather weak, so we tend to explicitly refer to "alerts or recommendations". It's a lot more characters and can sound clumsy in some contexts.

In the code, as developers delight in telling me, there is no such distinction. In the code, everything is an "incident". Go figure.

Groups or templates?

Another area of much debate concerned "templates". In the first BETA iteration of SQL Response, you could control the settings across a number of monitored SQL Servers at once by adding them to a "group" – a Development group, or a Production group, whatever you wanted. This seemed pretty intuitive. "Group" is a common word and easy enough to understand.

“
...in the battleground
between precision
and accessibility, we
try to find a balance.
But that balance of
meaning is constantly
evolving...
                   ”

Following lots of usability reviews, it was decided that "groups" wasn't the right word to indicate the far-reaching effects of how a group was used (to change the settings on lots of things simultaneously). Also, "group" could be misleading, if users simply wanted to view certain SQL Servers together.

We realised that we were overloading the meaning of the word "group". It was decided therefore to ditch the "group" altogether and introduce….. “The Template". It's a more technical, less 'universal' word, but it's more specific in its definition, and more importantly, it matches the behaviour in SQL Response more closely.

This caused me a few headaches as a technical writer. Do you "add" something to a template? Can you "move" SQL Servers from one template to another? I was happier with groups, because a group to me had a clearer conception in my simplistic imagination than a template. I could visualize those SQL Servers, huddled together in their tribal camps. A template is a more nebulous concept.

Again, in the battleground between precision and accessibility, we try to find a balance. But that balance of meaning is constantly evolving with changes in society and other software products like Chrome making our job endlessly interesting. ‘Meaning’ is a concept shared between speaker and listener, or author and reader; understanding breaks down when one party invents a meaning unilaterally. So believe me when I say that every detail has to be scrutinised, every word and synonym considered, and every decision carefully measured.