Category Archives: language

Do you use singular or plural after “types of”

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:

A kookaburra looking goofy

What languages do our readers speak – from Google Analytics

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.

Summary

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:

Top 10 locales via Google Analytics

Top 10 locales via Google Analytics

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.

The figures

Here are the figures that back the above graph:

Locale Number of visits Percentage of total
1. en-us 1,951,818 66.75%
2. en-gb 163,897 5.60%
3. de 105,526 3.61%
4. de-de 102,578 3.51%
5. fr 77,666 2.66%
6. ru 66,342 2.27%
7. zh-cn 38,850 1.33%
8. en 38,826 1.33%
9. es 37,129 1.27%
10. pl 30,064 1.03%

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. :)

What colour is your document – etymology visualisation

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:
    <div class="messagebody">
  • 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:
    <span class="lat">Confluence</span> <span class="oeg">is</span>
  • 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. :)

Is it OK to say PDFs

Is it OK to say “PDFs” instead of “PDF files” or “PDF documents”? A colleague, Paul, and I were discussing this crucial question a few days ago.

How about “emails” instead of “email messages”? Or, horror of horrors, “XMLs” instead of “XML files”? Believe it or not, I’ve seen that one crop up in our documentation. I’ve yet to see or hear anyone talk about “HTMLs” but even that’s not beyond the bounds of possibility. ;)

Actually, I’ve grown accustomed to hearing “emails” and can even be heard to use that word myself on occasion. But I still try to steer clear of it in technical documentation. The use of “PDFs” irks me, and I doubt if I’ll ever like “XMLs”. But never say never.

Paul and I decided that our primary aim is to make sure the meaning is clear and to avoid annoying our readers. After all, as technical writers, we want to give people a smooth ride through the text.

What do you think?

Am I being a stickler for detail?

Talking of sticks, this gorgeous visitor appeared on our postbox a few days ago. It’s a stick insect. I put the peg there to give an idea of scale. The stick insect has six legs, two of which are close together on the right hand side of the picture. Its head is on the left.

Is it OK to say PDFs

A stick insect on my letterbox

Follow

Get every new post delivered to your Inbox.

Join 1,499 other followers

%d bloggers like this: