Making Heads or Tails of Coin Names in Technical Documentation

Legacy manuals are like junk-filled beaches – they keep throwing up something mundane. However, occasionally the manuals offer something a bit weirder. I was rewriting the user guide (operations manual) for a ticket vending machine (TVM) and came across the way coins were referred to in the guide.

Let’s dissect…

Some TVMs accept bank notes and coins whereas other TVMs accept smart cards and bank cards (credit and debit). Coin operated TVMs have a coin slot that accepts coins.

In the US coins are known by many names such as cent, nickel, dime, and quarter.
Such coin naming conventions are limited to the US and a few other English-speaking countries. Even if the US money – coins and bills – are used for exchange purposes in other countries, they are just known as US dollars.

Thus, some of the US coin terminology is limited to the US. Obviously!

But the world has other countries as well. Here is a list of coin currencies across the world:

  • European union coins are simply known by their denominations such as 1 cent, 2 cent, 1 euro, and 2 euro.
  • Australia has dollars and cents.
  • The UK has pound sterling, penny, and pence.
  • Ruble and kopeck are Russian.
  • Kazakhstan’s coins are tenge.
  • In India, Pakistan, and Srilanka the currency is rupee.
  • Argentinian centavos and pesos aren’t as famous as the pampas or Diego Maradona.
  • It is dirham in UAE and riyal in Saudi Arabia.
  • Laos deals in kip.
  • Peru’s coins are Peruvian soles.
  • Jordan has dinar.
  • Angolan currency is kwanza and Nigeria has kobo and naira coins.

Thus, you cannot call all the currencies (coins and bank notes) by a single name.

However, you can call coins as coins!

On to technical documentation…

The TVM that I was writing the manual for is used across the USA and probably Canada. A routine procedure instructing the user to insert coins in the coin slot of the TVM had this:

“You cannot insert coins larger than Susan B. Anthony or Sacagawea dollar coins.”

I did not know who Susan B Anthony was. Pardon my poor history. Yet, this is akin to saying “Mohandas Gandhi coins” in India or “Tetyana Yablonska coins” in Ukraine or “Haji Hassanal Bolkiah coins” in Brunei.

This usage is local and even colloquial. A simple rewrite is needed:

“You cannot insert coins larger than x diameter and y thickness.”

At times, we assume that others know what we are writing about. To overcome such usage, we have global writing standards and technical documentation standards. And then we have common sense.

The ocean brings in routine junk to the beaches. Occasionally, we spot something a bit different and weird. Legacy documentation too has this tendency of springing up something surprising.

Writers need to clean up the mess in the documents!

Unburdening the Parentheses (round brackets): Suggestion to Use a New Symbol for Acronyms and Abbreviations

In sentences, parentheses (or round brackets) is used:

  • To set off information that is useful to the reader
  • In place of Em dashes or commas
  • To provide remarks, additional information, cross-references, definitions, or acronyms

Let us look at some examples of the many ways in which parentheses are used in technical documentation:

Purpose of Parentheses Examples
For direct reference to a location in a document
  • Figure 1: Front Door Layout (Left); Rear Door Layout (Right).
  • Insert the key into the threaded holes (see Table 6).
To provide additional information that the reader can do without but which will be quite useful
  • Connection assembly (vertical and horizontal) description is available online.
  • Enter the serial number (if applicable).
  • This rating is required by the Rules Group (standard authority).
  • If you want to use separate plug-ins (such as Application Control or Network Manager), install the plug-ins before updating the server.
For giving timely information that is very useful for non-technical users
  • Adjust your browser zoom (CTRL/CMD + or CTRL/CMD -)
  • The authoring tool remembers your choice (menu open or closed) in a session.
  • Use the minus sign (hyphen on the keyboard).
To provide specifics or other names of an entry
  • Edit database storage structures (tablespaces)
  • Create database objects (such as tables and indexes)
Where without the information the user might lose their way or unnecessarily perform some steps
  • To specify your product type, use a license manager (if it is a concurrent-use product), or provide authorization rights to your software (in case yours is a single-use product).
  • Use your computer (for local configuration) or VPN (for remote configuration).
  • Install SQL Server Express to store the database objects (optional).

There are other examples but overall, parentheses make the meaning of the sentence clear. Parentheses hold additional information.

Here are some acronyms:

  • Ticket vending machine (TVM)
  • Microsoft Manual of Style for Technical Publications (MSTP)
  • For more information, see the master document list (MDL) of the project.
  • The functional design specification (FDS) lists the features for the current release.
  • Secure socket layer (SSL)
  • Hardware Management Console (HMC) virtual appliance (HMC virtual appliance).

By acronyms I also mean the common ones such as UI, PDF, LASER, dpi, and GB.

Note: I am not getting into the differences between acronyms and abbreviations. This post is about the usage of parentheses for abbreviations.

While parentheses for holding additional information between the round brackets “(“ and “)” is fine, the use of parentheses for acronyms (including initialisms and other abbreviations) seems odd.

Yes, writers and editors have been using it for such a long time…but there seems to be a lack of parallelism. The information within the parentheses is always additional. But in the case of acronyms and abbreviations, the parentheses hold a shorter form.

So, shouldn’t there be a difference?

True, I can hear some shrill and coarse voices saying, “that’s not the end of the world”. Sure, I agree – it is not yet the end of the world. But take it as a suggestion and why not? We strive to improve quality through editing. This might help.

I felt that the round brackets are overloaded. They hold everything inside and they play a part in mathematics too. Therefore, I want to help the round brackets shed a slight load!

My suggestion is to use a different type of symbol for acronyms instead of the parentheses. The curly braces “{ACRONYM}” or the square bracket “[ACRONYM]”? But these are used in equations a lot. The pipe symbol |ACRONYM| is used in programming statements. So that leaves us very little choice.

Here are some ideas that can be used. But it would involve creating a new keyboard character or additional typing.
___________
) ACRONYM (
___________
| ACRONYM |
_________
{ACRONYM}
___________
> ACRONYM <

Thus, I am forced to suggest round brackets but inverted. The new way of way notating acronyms and abbreviations will look as follows:

) ACRONYM (

This will be easy to remember and in time will be accepted as the norm.

The style guides of this world—)MSTP(, )IBM(, )APA(, )SPE(, and so on—should listen in. In case, this symbol is used elsewhere – then let us invent a new symbol.

If you have read this far, then you will provide your feedback or comments (I hope!)

Samsung Galaxy J7 Prime – Bike Mode is a Ride with Some Bumps (Online Help is no Help as well)


The Samsung Galaxy J7 Prime has a unique feature – the Bike Mode (S bike mode) – and that’s what we will take a quick peek at.
The smartphone is a decent device and works quiet satisfactorily. The power-saving mode keeps your battery for long without disabling the most used features. The metal body finish is nice, the phone has an easy mode, abundant accessibility features, useful one-handed operation, fingerprint scanner, and so on. On the flip side, the J7 Prime lacks a gyroscope, camera is not great, and design is normal. The phone is okay overall.
However, here am not out to review the phone – just want to write about the S Bike Mode and the associated Online Help.
The bike mode was developed for two-wheeler riders. Many ride two-wheelers to work every day. When driving a car, the driver can afford to answer phone calls by using a hands-free headset or through the speaker. However, with bikes, the key element is driver balance and the need to use both hands to control the bike. Of course, even on cars drivers must be careful and not get distracted by phone calls. Yet, comparatively, car drivers can answer important calls unlike bike riders who will take a risk if they answer mobile phone calls.
Therefore, Samsung has developed the bike mode that will let callers know that the person who they called is riding a bike. The rider too will not be able to answer calls when in that mode. Callers can press 1 to let the rider know of urgent calls. The device rings at the highest volume and vibrates in case of urgent calls. However, the rider can answer the call only after slowing down the bike or stopping.
The rider can use preset messages to auto answer callers.
At least this is the intended way for the bike mode to work.
Okay I put the bike mode to test – and these were my initial observations:
In the mobile phone, I noticed this…
In J7 Prime Online Help, I looked up for more information…
1
The urgent mode works only for one of the SIM cards! The J7 prime has two SIM card slots. If the caller calls the second number, they hear the message that the user is busy. Auto answer works only for one number.
After a bit of tinkering I realized that callers get the same message on both the SIM cards if I just switch on the ”Reject Calls while Roaming” option within the S Bike Mode settings.
Unfortunately, online help does not mention this. Incidentally, this is not the right solution for auto answer on both SIM cards.
2
Am not sure how the motion detector works. The device works in much the same way when not riding. So if a caller calls, they get the same message that the person is riding a bike. Does it mean that the motion detector is a gimmick? Maybe it is just not smart enough to detect stationary objects!
Could have mentioned this in Help.
3
I was unable to set up any custom auto answers for selected contacts.
Would have been a good value addition as I would want only certain people to know that I ride a bike (or my location).
4
I was also not able to create my own specific text messages for selected contacts. Nor did the recipient get location-related smart replies when their calls were not answered.
The bike mode needs a data connection to work. However, they should have included offline help. Maybe a video or demo would have been useful. Remember in this case the user is the rider.
So the S Bike Mode is okayish but nothing great. Fundamentally, the urgent calls feature should be reconsidered as the idea is not to use phones while riding. Unless the urgent call automatically slows down the bike or provides some such physical warnings, this is not a safe option. Moreover, in some parts of the world, the streets are noisy and it is very tough to hear or feel a mobile vibrating. Even at the loudest, the urgent calls might go unanswered.
Looks like Help was not field-tested.
 
 Neither the bike mode nor the Online Help is useful.

Windows7-Nokia Lumia 800 – two taps too many and no help in sight

Note: Although the following looks like text, these are images (Blogger did not allow me to re-size images within blog posts). Click on each image to read.


Addendum:  Finally, “Help + How-To” worked! This is possibly WebHelp mobile output (that is htm pages for mobiles) and can be viewed in the default viewer (no need to launch a browser to view the topics). No ePub downloads are needed (such as PDF or Kindle for example). However, internet connection is needed and Help is not available offline. This is where the Mobile Phone’s sync problems take its toll.

Note that the term “Tile” is used for Icons, “Start” for Home screen, and “Flick” to describe the touch screen slide gesture.

Parallelism when writing for Tablets

I was writing an install procedure for one of our software products (for tablets) and just thought I should share my thoughts on the style for referring to tablet names.
I compiled a list of tablets available in the market.
 
Company
Device
Software
Usual name
Amazon
Kindle
Android
Amazon Kindle
Barnes and Noble
Nook Color eBook
Android
Nook
Samsung
Galaxy
Android
Samsung Galaxy Tab
Toshiba
Excite
Thrive
Android
Toshiba Excite
Toshiba Thrive
Dell
Streak
Android
Dell Streak
Lenovo
K1 Ideapad
Android
Lenovo Ideapad
Sony
Tablet S
Android
Sony Tablet S
Motorola
XOOM
Android
Motorola Xoom
HTC
Evo View
Android
HTC Sprint
Google
Nexus
Android
Google Nexus
Apple
iPad
Apple OS
Apple iPad
BlackBerry
Playbook
BlackBerry OS
BlackBerry Playbook
HP
TouchPad
HP Web OS
HP TouchPad
Samsung
Slate PC
Windows 7 Home Premium
Samsung Series 7 Slate PC
Acer
ICONIA
Windows 7 HomePremium32 bit
Acer ICONIA
HP
Slate
Windows 7 Professional
HP Slate
                                                                                                                                                                
The usual features users need are size, storage, Internet connectivity (WiFi), apps, etc. The tablets run on different processors and Operating System (OS). However, the OS seems to be the main category by which tablets are known.

The three most popular OS are: Apple OS, Android, and Windows.
The “devices” are known by different names. For example:
  • Apple’s tablet is iPad
  • Blackberry’s tablet is Playbook
  • Dell’s tablet is Streak
Devices that run on Android (as many companies offer these tablets) are commonly known as Android tablets. Of course end users might know and buy Motorola Xoom or Samsung Galaxy tab with Android, etc.
Similarly for tablets that run on Windows, the usual reference is to Windows tablets.
So when writing a procedure (probably installation and configuration procedures) for a product that works on a specific tablet, the heading would be:
– My Product Procedure for iPad (not Apple iOS 5 – the OS for apple tablets!)
– My Product Procedure for Android tablets
– My Product Procedure for Windows tablets
Note that we call iPad – the device – Apple iPad. This is the deviation in style! We skip Google in the Android name and Microsoft in the Windows reference.
Strictly…if we write a procedure titled, My Product Procedure for Apple iPad, referring to the device name, then we should have My Product Procedure for Samsung Galaxy tab or My Product Procedure for Acer ICONIA! But that would be going overboard and into too much detail. What we actually mean is: “My Product Procedure for Tablets that run a) Apple OS b) Windows OS c) Android OS, and so on.”
Therefore, I think it is best to keep it as My Product Procedure for Windows Tablets or My Product Procedure for Android Tablets. The plural form “tablets” is NEEDED to cover all tablets that run on Windows or Android. (I also read somewhere that tablets and tablet PCs mean the same.)
The only problem would be if at all a different company other than Apple suddenly offers their own tablets with Apple OS! Then we might need to change the heading for the My Product Procedure for iPad to “My Product Procedure for iPad tablets”! Or ask Apple to make their OS name popular 🙂

Unfriendly Error Message on Google Chrome Browser

I logged on to http://www.hdfclife.com/ using Google Chrome and got the following error message when I tried to click on a link for making a transaction:

Diffie-Hellman is a cryptographic technique (cipher security method for authentication). This works like RSA algorithms and uses public-private keys to exchange information between two mediums securely. To describe rather vaguely, first, information that needs to be exchanged is encrypted and assigned two secret keys – public key and private key. This encrypted information can be decrypted only if you have both the keys. Someone might get hold of the public key as it is available publicly during transactions. However, this information is useless as the private key is required to decrypt the data. BOTH private keys are needed to exchange information. A simple example could be the several banking web sites that offer customers a device to generate their own private keys which the customer would use to log in to the banking website. The security methods vary and often keys are used in combination with passwords, tokens, or other authentication means.

Anyhow, the point of this post is not to delve into cryptographic keys. You can get information on cryptography and keys on the world wide web.

I want to talk about this particular error message.

Diffie-Hellman technique can be implemented in 3 different ways:

  1. Anonymous key exchange (Keys are exchanged without authentication and is a weak method)
  2. Fixed key exchange (here known keys are exchanged and is reasonable secure)
  3. Ephemeral Key exchange (here the keys are temporary and created during the transaction and is a strong method).

Ephemeral = Temporary
Ephemeral is a word often used in literature but avoided in technical and user documents. Although, it is used in the textual description as “ephemeral Diffie-Hellman public key”, this error message should have been rephrased. Something like “Connection on this website is not secure.”

Then the next sentence has the phrase “disastrous misconfiguration”. This is really scary! Could have read as “This is a problem with the server on the website you tried to log into.

Next the marketing slant “Chrome won’t use…”

Which user likes to see such unfriendly error messages? The same website however worked when I used Internet Explorer!