When should we use one word, when should we use two, for terms like “log in”, “sign up”, “back up”, and the like? This is a hot topic among technical writers, UX writers, and any designers who use text in their products.
The question is particularly relevant in the software industry, but it affects other product areas too. For example, a gym may invite customers to an exercise class with wording like this:
We promise you a great workout
Work out with your friends and colleagues
How can we tell whether we should use one word or two?
Even if we ourselves already know the difference, how can we teach other people, like the engineers, designers, product managers, and other people who work on our product interfaces and documentation?
A presentation – a bit of fun with a serious goal
I’ve put together a presentation that explains a way to help ourselves and others decide when to use one word, when to use two. It’s a bit of fun, but with a serious goal.
You can find the presentation on SlideShare: One word or two? How to teach the difference between “login” and “log in”, and other mind-bogglingly important compound words.
This blog post contains some extracts from the presentation.
The presentation shows a couple of slides containing a few sentences. Embedded in the sentences are some strings of repeated letters, like lllll or bbbbb.
To play along, you’ll need to replace the string of letters with the terms “log in” or “back up”.
Try speaking the sentences in your head., or even saying them out loud. This is where the bit comes in about your partner needing to be in a good mood: you could even ask your partner to play along with you!
In the first slide, replace llllllll with “log in”
Here’s the first slide with letters for replacement – replace each series of lllll with “log in”. Don’t write anything down – just say the sentences in your head or out loud:
In the next slide – replace bbbbb with “back up”:
What’s the outcome?
Did you notice any pattern in the way you pronounced the words “login” and “log in”?
If you’re like me, your stress pattern in the middle sentence is different from the first and third sentences.
In the middle sentence, we give equal emphasis to both parts of the phrase: log in.
In the first and third sentences, we give greater emphasis to the first part of the phrase: login.
The stress patterns are the same for backup.
In the middle sentence, we give equal emphasis to both parts of the phrase: back up; log in.
In the first and third sentences, we give greater emphasis to the first part of the phrase: backup; login.
And it’s the middle sentence that uses two words, while the first and third use one word.
So, you can use stress patterns to decide whether to use one word or two.
That’s one way of doing things, but what’s the theory behind it?
The rules are something like this:
- If the phrase is acting as a noun, use one word. This includes cases when the phrase is used to qualify another noun.
- If it’s a verb, use two words.
The presentation goes into more detail and includes some sources and additional reading.
What about hyphens?
Yes, what about hyphens. I think this is my favourite slide, because it shows a pic of a Tawny Frogmouth. They’re the coolest birds ever.
I’ll leave you to read the rest in the presentation itself
The complete presentation is on SlideShare: One word or two? How to teach the difference between “login” and “log in”, and other mind-bogglingly important compound words.
(Note: This presentation is a prettified and updated version of my earlier blog post, published in April 2014. There’s a spider in that one.)
If you can insert the words “by zombies” into a sentence, then that sentence very likely uses the passive voice. A colleague recently reminded me of this tip. It made me laugh, and so I thought it’s worth blogging about. If only to share the chuckle.
Here are some examples of zombie-infested sentences, and their equivalents using active voice.
Geographic requests are indicated by zombies through use of the
coordinatesparameter, indicating the specific locations passed by zombies as latitude/longitude values.
Converting passive voice to active:
You can use the
coordinatesparameter to indicate geographic requests, passing the specific locations as latitude/longitude values.
For an even more concise effect, use the imperative:
coordinatesparameter to indicate geographic requests, passing the specific locations as latitude/longitude values.
Latitude and longitude coordinate strings are defined by zombies as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.
Converting passive to active imperative:
Define latitude and longitude coordinates as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.
Why eliminate the zombie vulnerability?
Active voice is more concise than passive voice. It’s usually easier to understand.
To me, the most important point is that active voice makes it clear who’s responsible for what. Putting zombies aside, if you use the passive voice your readers may think that the nebulous “system” may do the thing you’re talking about.
Who does what, in this example?
The API can return results restricted to a specific type. The restriction is specified using the
Answer: The developer has to specify the types in the
types filter. I don’t think that’s clear, though, when reading the text. Often the context makes it clear, but not always. Zombies lurk in the shadows, ready to grab the unsuspecting reader.
The distinction between active voice and imperative mood
In the above examples I’ve pointed out the difference between active voice and imperative mood. In technical writing, both are good. The imperative mood is particularly concise and clear, but in some cases it can come across as too abrupt.
Should we ever invite zombies in?
I think there are times when passive voice is OK, or even a good thing. Sometimes a sentence sounds artificial if you attempt to inject a subject. Sometimes the passive wording is a well known phrase that readers will accept and understand more easily than the equivalent active phrasing. For example, what do you think of this wording?
These community-supported client libraries are open-sourced under the Apache 2.0 License and are available for download and contributions on GitHub. The libraries are not covered by the standard support agreement.
‘Login’ or ‘log in’? One word or two? It’s an oft-debated question. I’m not proposing a hard-and-fast rule, though I do have my preferences. What this post offers is a handy way of choosing between one word and two, if it’s important to you.
It’s not just logging in that’s affected. There are plenty more cases where we need to choose one word or two:
- ‘logon’ or ‘log on’
- ‘logout’ or ‘log out’
- ‘signup’ or ‘sign up’
- ‘shutdown’ or ‘shut down’
- ‘backup’ or ‘back up’
- ‘setup’ or ‘set up’
- and more, including words not related to computing, such as ‘workout’ versus ‘work out’
Who’s up for an experiment?
Warning: Don’t try this at home, unless your partner is in a good mood.
Try speaking these sentences out loud, replacing ‘bbbbbbb’ with ‘backup’ and ignoring the spelling for now:
- What is your bbbbbbb strategy?
- When did you last bbbbbbb your data?
- When did you last do a bbbbbbb?
Now try these, replacing ‘llllllll’ with ‘login’:
- What are your llllllll details?
- Where can I llllllll to the bank’s website?
- My llllllll failed.
Did you notice any pattern in the way you pronounced the words “back/up” and “log/in”? If you’re like me, your stress pattern in the middle sentences would be different from the first and third sentences.
- In the middle sentence, you would give equal emphasis to both parts of the phrase: back up; log in.
- In the first and third sentences, you would give greater emphasis to the first part of the phrase: backup; login.
And the answer is…
‘Backup’ or ‘back up’:
- What is your backup strategy?
- When did you last back up your data?
- When did you last do a backup?
‘Login’ or ‘log in’:
- What are your login details?
- Where can I log in to the bank’s website?
- My login failed.
Rules and things
It may be that you decide to go with the growing common usage, and just use one word (like ‘login’) for everything. But if you want to follow the ‘rules’, they’re something like this:
- If it’s a verb, use two words.
- If it’s a noun, including cases when the noun is used to qualify another noun, use one word.
What about hyphens (‘-‘)? Technical writers try to avoid them.
Who decreed that this is how it’s done, and where is it written down? Most tech writers and other guardians of language would agree that we should be descriptive rather than prescriptive, and that there are a equally-viable alternatives out there. But we also agree that it’s good to have a standard, so that our readers have a smooth ride through the documentation and application screens.
Here are some style guides and commentaries that agree we use one word for a noun, two for a verb:
- Guardian and Observer Style Guide – Scroll down to the entries for ‘log in’ and ‘login’.
- Apple Style Guide – See the entry for ‘log in (v.), login (n., adj.), log out (v.), logout (n., adj.)‘, on page 96.
- Log in vs. login by Grammarist – This post has some useful examples from online newspapers.
- A thread on the English Language and Usage Stack Exchange – People express various opinions, but the consensus is one word for a noun, two for a verb.
- Another thread on the English Language and Usage Stack Exchange – This one is particularly cool, because someone pointed out in a comment that the instructions on the Stack Exchange page itself said ‘Sign up or login’, and Stack Exchange fixed it!
- The Wikipedia page on login – The page consistently uses ‘login’ as a noun and ‘log in’ as a verb. It also states, ‘The noun login comes from the verb (to) log in‘.
- And someone who has a strong opinion, backed up by good research: “Login” is not a verb.
Who cares? Is this a difference between US and British usage? I don’t think so. It’s more a difference between people who feel a sense of jarring disconnect when someone uses ‘login’ and the like as a verb, and people who don’t. If you do want to differentiate, the pronunciation test may be the quickest way to decide whether you need one word or two.
There’s only one word for this spider: Eek!
This spider took up residence between my window panels for a while. It’s a huntsman: huge, very fast, scary but beautiful, and largely harmless. I put the peg there for scale. It’s a large peg.
Actually, I’m fond of the gerund myself. I’m not seriously proposing we kill it, but I’d love to know what everyone thinks about using, or not using, gerunds in headings and page titles.
A gerund is an “-ing” word, like “adding” or “removing”. More specifically, it’s the “-ing” form of a verb when used as a noun. Most technical documentation uses gerunds in topic titles and page headings, like this:
- Adding a widget
- Deleting a widget
- Installing a widget
Examples of the traditional way:
Brave new world
We’re trying an experiment with short-form verbs in headings. Instead of gerunds, we’re using just the verb stems. So, instead of “adding a widget” we’re saying “add a widget”. This looks like an imperative, but it’s not meant as such. It’s just a short form of the verb, and more likely to match what people will search for on the page (using Ctrl+F, for example). It’s tempting to cite web searches as well, but any search engine worth its salt will find the stem of the word and return all results matching the stem.
Examples from our documentation:
At the moment, we’re leaving gerunds in the page titles (primarily for consistency across the documentation suite) and just changing the headings within the pages.
Others who’ve killed the gerund:
At university, I studied English with a strong emphasis on linguistics. This week a colleague at work, after reading my recent blog posts about language, let me know that she had studied linguistics too. So why are we both now in Information Technology (IT)? Also, John R made a thought-provoking comment. So now I’m following up on those two comments. And at the end, I’ll tell you how my trees are doing.
First of all, exactly why is this sentence funny or at least quirky: “Drive carefully when wet”?
Secondly, John R’s comment got me to thinking about how, with my fascination for linguistics, I ended up in IT. What makes a technical writer tick, and is the tick-mechanism anything like the widget that powers a systems engineer? Do John R (a self-professed ‘computationist’) and I (a linguaphile) actually share a habit of putting brackets around things and even indulging in the odd XOR?
Linguists have spent a lot of time trying to describe the knowledge common to speakers of a particular language. Without a shared knowledge, we wouldn’t be able to communicate. Some linguists think that there’s even an innate structural understanding shared by all humans, irrespective of which language they speak. So our brains come pre-wired with the “deep structural” rules of language, and we just have to plug in the specific language we need.
It seems fairly obvious that a language has a structure, and that all speakers of the language are able to manipulate the structure to produce unique, never-before spoken sentences with amazing ease. But describing the structure and its ability to generate new sentences has proved quite tricky.
Still, there’s hope. Take our sentence “Drive carefully when wet”. You might represent it like this:
Read the diagram starting from the top: A sentence (S) may consist of a noun phrase (NP) and a verb phrase (VP). A noun phrase may consist of a pronoun (Pro). A verb phrase may consist of a verb (V) plus an adverb (Adv) plus another sentence. And so on.
Linguists have also created a way to describe phrase-structure rules, complete with brackets and symbols to keep computationists 😉 happy. For example:
- S –> NP VP (A sentence may consist of a noun phrase and a verb phrase)
- NP –> Pro (A noun phrase may consist of a pronoun)
- And so on.
And then you can add other logistical provisions, like:
- “You” deletion: In an imperative sentence (i.e. a command), omit the “you”.
- Pronoun matching: The second pronoun, also missing in our sentence, is assumed to be the same as the first pronoun.
……So…… that’s why it’s funny. Get it? 🙂
The design of computer languages, and other artificial languages, owes much to the work of linguists. Chomsky, in particular, is an easy mark. He’s the man everyone loves to shoot down. But his work on the theory of a universal grammar, transformational-generative grammars, the Chomsky hierarchy and the Chomsky normal form set the basis for much of what we do today.
So that may be why my colleague and I, linguists both, found our way into IT.
I think there are probably two sorts (or more 🙂 ) of people. Those like me, who seem to organise things into groups automatically (yeah, those brackets). The groupings are fluid and flexible, but the fact remains that we like them to be there. And then there are the people who float much more freely in their ecosystems: go with the flow, synchronicity rocks, hey man what’s the odd misplaced pronoun between friends?
Sometimes it amazes me how many different world views there are out there, just walking down the street next to me. And that we actually do manage to communicate with each other!
Moving on to my two trees:
Two months ago, I planted two trees. I promised a progress report every now and then. The trees are about the same age as this blog. And they’re doing great.
Here’s the paperbark, now 50cm high. (Was 40cm on 1 September.)
Here’s the old man banksia, now 32cm. (Was 17cm on 1 September.)