Numb3rs in technical documentation

Numerals, dates, times in technical communications

Origins, selected translations of numerals. (Wikipedia)

Origins, selected translations of numerals. (Wikipedia)

Technical expressions of percentages, counts, temperatures, times and other numbers stuff are different from numeric expressions in marketing content. Generally, user guides and most process documentation follow the general audience guidelines more closely than scientific or technical descriptions for an expert audience.

  • The under-ten rule of spelling out numerals is not usually applied. For instance, 1 byte is always 8 bits. The file is 3.2 GB.
  • Percentages use both the numeral and the % symbol, except when beginning a sentence with a percentage. Examples: Fifty percent of the test runs failed. We guarantee 99.99% uptime. 
  • Most measures in technical documentation are written using the metric system. As a result, where a 2 by 4 is  2 by 4 in., the surface area of a microchip might a o.4 x o.2 mm rectangle. Most abbreviations for English measures are followed by a period; metric units are not.
  • In very technical documents (not most user guides), use all numerals for a dates and times. The ISO rule is to move left t0 right from the largest chunk to the smallest 2013-3-2: and 14:34:12 UTC. By this logic, the wheel might have been invented BC 2013-3-2, 14:34:12 UTC! The designation UTC is equal (within milliseconds) to GMT. Some writers use UTC (Coordinated Universal Time) does not change with different locations’ imposition of Daylight Savings Time. To indicate your location, you may (I don’t know why) want to use UTC offsets such as UTC-5:00 or UTC R, either of which indicates US Eastern Time. See complete listing here.
  • Decimal expressions are well known; the only real question is how precise (long) your expressions are. If you use a binary, hexadecimal, and octal number base (radix), you will need to say so. How you do this depends on your audience and the coding environment. There is a rarely used but straightforward way to signify which radix you are using: xx2, xx8 or xx16 , but for lots of reasons, these notations don’t work in different computing environments. (For instance, the line under the above subscripted elements is wrong because I’m using HTML and have not adjusted the line spacing command.)
    1. Binary code is generating what I’m writing, transmits it and makes it appear where your are. Most people know that ASCII defines keyboard characters, although Unicode encompasses a much larger character set. Usually  binary values are expressed in groups of four 0s and 1s separated by a space, with many exceptions such as 7-bit ASCII designations. A b or B is often appended to a binary set, but 0B, bin and % sometimes are prepended to a binary numeral.
    2. Octals are used in IP addresses and, in many address hardwares such as memory and address drivers, clock drivers and bus oriented transmitter/receivers. Usually octals are not expressed with commas or spaces. If you document hardware using octals, check with your SME about the company’s guidelines for octal expressions.
    3. Signifying hexadecimal expressions, which have by-and-large replaced octals in software computing,  varies depending on the “language” you’re speaking. Wikipedia lists 23 different contexts in which hex notations are signified uniquely. Among these are Web addressing (prefix %), XML and XHTMl for characters (Unicode standard, but prefix &#x), HTML and CSS-abbreviated color references (prefix #), C-, C+, C++, Java, Javascript and others (prefix 0x), IBM X or Hex with numerals in single quotes and so on. Again, it’s best to check with your SME before you begin.

Software and hardware names often include numbers: Windows 8—interesting that MS could not get a trademark for this name—Intel® Core™ i7 Processor, etc. Lawyers get involved in product naming, and you will find that getting copy by the legal department requires consistency and precision. For instance many companies require that the product or company name never be used as a possessive: IBM’s new mainframe ( a no-n0). Others are happy to become verbs: Did you Google me?

The writer should always consult the legal department about names of products and services, and you would be wise to familiarize yourself with some intellectual property law. This is especially true when you are working  with a startup. Often, the creators of a technologies learn hard lessons in law after the fact. A good technical writer asks questions: “What is the legal status of this product name or process? Have we registered it with the US copyright office?”

 

 

Tagged with: , , , , ,
Posted in Editorial Style, Technical Documentation

Leave a Reply

Your email address will not be published. Required fields are marked *

*

* Copy This Password *

* Type Or Paste Password Here *

%d bloggers like this: