Category Archives: language
What’s the difference between delete and remove? When should you use the word “delete” on a user interface or in a document, and when “remove”? Here’s an explanation that makes sense to me.
Use “delete” when you’re getting rid of the thing entirely – when it’s disappearing from the data store. Use “remove” when you’re subtracting it from a group or a list, but it remains available in the data store.
An example is the model of users and groups. Let’s say the user
arthurdent belongs to two groups:
earthlings. When Arthur no longer lives on planet Earth, you would remove
arthurdent from the
earthlings group. But if Arthur has departed the universe without leaving so much as a towel behind, you would delete the username
Here’s another example. Let’s say you have a number of credit card charges, which you’re adding to two expense reports. By mistake, you’ve added one of the charges to Expense Report 1 as well as Expense Report 2. So you need to remove that charge from the report. In addition, there’s an erroneous credit card charge of zero dollars, which you can delete without adding it to a report.
Works for me. :) What do you think?
‘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.
Would you say “two types of widget” or “two types of widgets”? In other words, should we use singular or plural after the phrase “types of”?
This is a real use case. In a code review this week, someone corrected my use of “types of widget”. People have varied and vociferous opinions. It’s intensely interesting, especially to technical writers.
Since I was a babe in arms, I’ve always used the singular:
“There are so many kinds of chocolate cookie! Which one shall I try next?”
“What are your favourite types of dog?”
To me this sequence just looks odd:
Pick one type of car.
Pick two types of cars.
Surely, if we can grant the English language a modicum of mathematical elegance ;) this should be correct:
Pick one type of car.
Pick two types of car.
So, why does the singular sound better to me? I think it’s because, when used after “types of”, the noun is acting as a concept representing a class of things, rather than a specific instance of the thing.
What do you think? Bring on the debate!
A kookaburra near my house:
I’ve grabbed some Google Analytics statistics about the languages used by visitors to the Atlassian documentation wiki. The information is based on the language setting in people’s browsers. It’s a pretty cool way of judging whether we need to translate our documentation!
The statistics cover a period of 3 months, from 7 September to 7 December 2012.
Approximately 30% of our readers speak a language other than English. The most popular non-English language is German (approximately 7%), followed by French (approx 2.6%). Japanese is hard to quantify, because we have separate sites for Japanese content.
The pretty picture
This graph shows the results for the top 10 locales:
The grey sector represents a number of smaller segments, each one below 1%. In Google Analytics, I can see them by requesting more than 10 lines of data.
Here are the figures that back the above graph:
|Locale||Number of visits||Percentage of total|
More Google Analytics?
Google Analytics is a useful tool. If you’re interested in a couple more posts about it, try the Google Analytics tag on this blog. I hope the posts are interesting. :)
For a bit of fun, I’ve been playing around with the Shakspere thread on the Etymology Discovery Message Board. It’s pretty cool. You paste in a chunk of text, and a text parser colours each word based on the etymology of the word. The parser recognises origins in Old Norse, German, Old English, Middle English, various flavours of French, Latin, and Greek.
When I started out, I thought we may be able to see some characteristic of technical documentation as opposed to other types of writing. For example, since technical documentation is rather forthright and not known for its romantic atmosphere, perhaps most of the words would be of Germanic or Old English origin. I guess medical texts would have a higher content of Latin than other writing does.
In fact, my very small samples don’t lead to any definite conclusions. That’s not surprising. In fact, one of my non-technical blog posts (“Jazz in Harlem”) has a higher Old English ratio that the technical documents.
Without further ado, here are the samples I chose, and the resulting etymological visualisations.
Colour coding on the etymology visualisation pages
The colour-coding on Shakspere is as follows:
(You’ve probably noticed the typo. I was tempted to fix it just for the screenshot – ha ha, been there, done that – but decided not to. If you haven’t noticed it, don’t worry. Spotting such things is one of the hazards of being a technical writer!)
Technical document: “About Confluence”
Source: A short document introducing Confluence wiki: About Confluence,
Etymology visualisation from Shakspere for “About Confluence”:
Etymology graph for “About Confluence”:
Technical document: “Installing JIRA on Windows”
Source: An installation guide for JIRA web app: Installing JIRA on Windows
Part of the etymology visualisation from Shakspere for “Installing JIRA on Windows”:
Etymology graph for “Installing JIRA on Windows”:
Technical blog post: “Comparing SharePoint and Confluence”
Source: A technical writer’s blog post (mine): Comparing SharePoint and Confluence.
Part of the etymology visualisation from Shakspere for “Comparing SharePoint and Confluence”:
Etymology graph for “Comparing SharePoint and Confluence”:
Quirky travel post: “Jazz in Harlem”
I picked this one because, although it’s mine, it’s very different from technical writing. I find it interesting how much Old English there is in this post.
Source: A blog post by the Travelling Worm: Jazz in Harlem, New York.
Part of the etymology visualisation from Shakspere for “Jazz in Harlem”:
Etymology graph for “Jazz in Harlem”:
Technical blog post: “Returning to Findability”
Source: A technical writer’s blog post from Tom Johnson: Returning to Findability.
Part of the etymology visualisation from Shakspere for “Returning to Findability”:
Etymology graph for “Returning to Findability”:
Technical blog post: “Improve tech comm by knowing a foreign language”
I found this one particularly interesting. The author of this sample, Kai Weber, is a technical writer whose first language is German. He does almost all his technical writing in English. I wondered if there would be a higher percentage of German words in the sample. But instead, there’s a significantly higher proportion of words from Old French than in other samples.
Source: A technical writer’s blog post from Kai Weber: Improve tech comm by knowing a foreign language.
Part of the etymology visualisation from Shakspere for “Improve tech comm by knowing a foreign language”:
Etymology graph for “Improve tech comm by knowing a foreign language”:
Company blog post: “Summit Aftermath – My 5 Highlights”
Given the above results, I thought it would be interesting to see another English post by a German author.
Source: A company blog post from Sven Peters: Summit Aftermath – My 5 Highlights.
Part of the etymology visualisation from Shakspere for “Summit Aftermath – My 5 Highlights”:
Etymology graph for “Summit Aftermath – My 5 Highlights”:
Technical blog post: “Facebook for Social Support? I like.”
Source: A technical writer’s blog post from Anne Gentle: Facebook for Social Support? I like.
Etymology visualisation from Shakspere for “Facebook for Social Support? I like.”
Etymology graph for “Facebook for Social Support? I like.”
How did I make the graphs?
The graphs in this post are derived from the data on the Shakspere pages. Here’s how I did it:
- Go to the Shakspere page that shows the colour-coded etymology. For example: a visualisation for “About Confluence”.
- View the HTML source of the page.
- Go to the bottom of the Shakspere HTML source to find the codes for each language that Shakspere recognises. This is what I found:
The colour-coding is as follows:<br /> <span class="onr">Words of Old Norse origin</span><br/> <span class="grm">Words of German origin</span><br/> <span class="oeg">Words of Old English origin</span><br/> <span class="mde">Words of Middle English origin</span><br/> <span class="ofr">Words of Old French origin</span><br/> <span class="frc">Words of French origin</span><br/> <span class="afr">Words of Anlgo-French origin</span><br/> <span class="mfr">Words of Middle French origin</span><br/> <span class="lat">Words of Latin origin</span><br/> <span class="mdl">Words of Middle Latin origin</span><br/> <span class="modl">Words of Modern Latin origin</span><br/> <span class="grk">Words of Greek origin</span><br/>
- Now move up in the HTML slightly, and find the line that contains this element:
- Copy the entire line from immediately after the above element, and paste it into Notepad++ or another text editor with a good “Find” function.
- You’ll see that each word has a semantic tag indicating the language derivation that Shakspere found. For example, in this extract the word “Confluence” is marked as Latin and the word “is” is marked as Old English:
- Use the “Find” function in Notepad++ to find the number of occurrences of each language.
- Put your findings into an Excel spreadsheet, with a column for the language and a column for the number of words found.
- Use Excel’s graph functions to create the graph.
Ready for more?
It was this post that led me to these etymological experiments: Visualizing English Word Origins, on the Ideas Illustrated blog.
Perhaps you have a medical text, or a romantic poem, to analyse? Drop it into Shakspere and let me know what you find. :)