Direction for Your Business

The consulting services of Strategy Sanity are multi-faceted and can be tailored to any need —

• Strategies, Programs, and even presentations can be analyzed and developed.
• Numerous Marketing and writing services are available.
• Extensive experience is the basis of many More abilities as well.
• In the technical arena, our strength is in embedded Processors, microcontrollers, digital signal processors, core processors, application processors, multi-core processors, and their application in electronic equipment.
• Traditional Market Research is performed in conjunction with Objective Analysis.
• Look into the Background and Biographies of our principals. Ask industry insiders or do a little Googling for our names, if there is not enough in the News and Events.

Contact Us

Copyright ©2007-2020, Strategy Sanity      The Walking Star is a trademark of Strategy Sanity

       
info@

  to inquire further –
StrategySanity.com

Technical Writing Style and Form

While generally the formal rules of grammar, sentence structure, spelling, and writing style in the English (or American-English) language should be followed in all writing, this analyst is a strong believer in a few deviations. The purpose for these differences is to enhance clarity and ease-of-use in the more complex and numerical technical world.

Acronyms: Be sure to spell them out but also sprinkle around the full phrase.

First it is good to point out a guideline that is apropos to the use of abbreviations and acronyms so prevalent in the Glossary on this Web site. This is a guideline that most authors follow fairly well. The first use of an abbreviation or acronym in a document should spell out the full term or phrase, and follow with the abbreviation or acronym that will be used further on in the document. This may look like "... digital signal processor (DSP)... The instrument uses a DSP to..."

Just because an acronym has been introduced does not preclude use of the full term or phrase. In fact, it is good to utilize the full string of words occasionally in later dialog to add emphasis, to remind the reader of the overall issue, or simply to break up the monotony of TLA TLA TLA TLA. This is especially true in long documents or where people may pull extracts out of the text and only be left with the mystical abbreviation in the out-take. It adds richness to revert back to the full phrase every four or five paragraphs. Remember that Web-based documents are often strung across a number of Web pages and that can leave the expansion of an abbreviation or acronym on a different page.

In some cases, space considerations make the above technique cumbersome. For instance in an illustration or in a presentation there may not be room to label a feature or write a concise bullet point using the fully spelled out name. In these instances, it is more useful to use the short abbreviation or acronym in the illustration or bullet point, but at the bottom of the page or otherwise reasonably in sight have a key or expansion of the shortening. This can be as simple as: DSP=digital signal processor  or  MU=million units shipped . This preserves the need for tight spacing without bewildering the uninitiated reader or listener with cryptic or unclear terms. If nothing else, a quick breakout of all the terms used should be provided at the end of the document or presentation.

Company Names: Treat much the same as Acronyms.

Company names come in various forms from formal to short-hand with legal ramifications that disturb lawyers. Readers don't want to be bothered with the cumbersome detail but are looking for the message hiding in the text. American Telephone and Telegraph may be called AT&T or ATT and it may also show a stock ticker symbol on the Dow as T, and there may be an Incorporated in there somewhere. Analog Devices is a company but each of those words are also common English words. In conversation a speaker might say "Analog" and be referring to the company Analog Devices, or he/she might say ADI (which stands for Analog Devices, Inc.). A company like Freescale Semiconductors is often simply called "Freescale" even by the company itself, and Freescale is a relatively made-up word, so there is some difference from the ADI example. MSFT (the stock symbol) is often seen in print as a short-hand for Microsoft Corporation (or is it Incorporated?)

While efforts should be made to comply with company desires for use of their trademarks, generally when writing one should apply similar rules of use to company names as to acronyms and abbreviations. That is, be sure the first use of the name is the more formal version, possibly with an indication of a shortened version to be subsequently used. Sometimes it is also helpful to give the shortest possible indication of the history of the name, such as: "Freescale Semiconductors (spun out from Motorola in 2003)" or "AT&T (sometimes referred to as 'Ma Bell')".

Some local style guides (such as in financial circles) have unique adders to include such as the ticker symbol, stock exchange, or recent price, or other information like country headquarters or current annual revenues. With company names it is not usually beneficial to revert back to the full corporate name later in the dialog as was suggested with acronyms and abbreviations, except where maybe bridging disparate Web pages. Product names and families can be tricky too, and should be handled similarly, but only with a good familiarity with how they are used in common practice. It is always good to assume the reader does not have the in-depth knowledge the writer does of the topic, and adding a few descriptive words before the product name (or following with a parenthetical phrase) can really help. Good examples might read like: "...the new cost-reduced R73 models have the same features as the popular P70 models on which they are based but also come in updated colors...". Give comparative specifics that any reader will relate to – although this is more of a content suggestion than a style guide.

Numbers: Go ahead and start a sentence with a numeral.

The general rule is to spell out all numbers from zero to ten and some milestone numbers like hundred or million. But in technology there are many situations where it is far clearer to always use the actual numeral. Engineers, scientists, and mathematicians are used to seeing numbers and often scan for them specifically. If the numbers are less visible because they are written out, they will be missed. Just glancing at the spelled out "ten" and the numerals "12" require an interpretation in the brain before they can be quickly compared as to which is bigger (perhaps a silly example but we do this a lot). Tables of numbers give weight to the advantage of always using numerals rather than occasional numbers in written word. A table would look ridiculous if every time the data tallied 9 or 10 it was written out as nine or ten, especially in the midst of 14, 36, 92, and 174.

The situation can be exacerbated when the number is the first word of a sentence or paragraph. Traditional rules dictate that the number is spelled out in words, even if it is a "big" number. While in some ways the value of initial capitalization to denote the start of a sentence may be lost if numerals begin the sentence, numerals at least also take up the full line height, and so may resemble initial caps. More important is that the numeral may especially draw the reader's attention to a critical highlight that is missed if converted to the word-equivalent. Again the size-comparison mentioned above plays into this. Consider the two versions of this sentence:

a)    Ninety-three million miles is a long way, but the 142 million miles from the Sun to Mars is 50% farther.

b)    93 million miles is a long way, but the 142 million miles from the Sun to Mars is 50% farther.

In b) all of the numbers appear as numerals and are easier for the mind to assimilate, almost making the 50% comment redundant to some readers. [As an aside, note that "farther" rather than "further" should only be used when referring to distances (to remember this rule, think of "far" as a distance).]

While nobody would ever suggest substituting a "1" for "One" in "One would assume that cows are heavy", anywhere that the number starting a sentence is there to give scale, that scale is emphasized in technical writing when it appears as a numeral.

Sentences can be re-worded sometimes to move the number from the first word, but this can change the emphasis or flow of the writing. "8-cylinder engines..." could be re-written "With 8-cylinder engines..." or even "Engines with 8 cylinders..." but that may subtly change the intent of the author. Ultimately, meaning and content should drive the sentence, not some rigid sense of formal style.

Numeral difficulty can be worse in the peculiar Olde Englishe style of highlighting the first letter of a paragraph by pulling it into an oversized exotic letter to start out the paragraph, sometimes called a "Drop Letter". This, too, could play havoc with spelled-out numbers – or it could work to an advantage if the first letter was actually an "8" or forced to a "16", where it delineated the description of the 8 versus the 16 sized discussion.

Note that hyphenated numbers can be especially tricky, as noted later in this piece.

Decimals, periods, and separators:
Favor mathematical clarity over punctuation niceties.

Decimals, points, periods, and other separators or delineators can be difficult when formulae (plural of formula) and numbers are included in normal text. The Web makes things more difficult both with HTML's difficulty in dealing with things that are conceptualized for hand-writing as well as limitations of fonts, superscripts, and the like on unknown displays. Just to show E=MC2 on a Web page usually requires special handling of the line spacing.

Additionally, periods ("dots"), slashes ("/"), and colons are used in new ways that may not fit well in sentence structures established well before the Internet or even computers were conceived. A period might be confusing to a rookie if it is at the end of a sentence that otherwise would have ended with the Web page html://www.domain.com/html. Does the period get typed or only the "dots" and does the reader know the difference? If there is a slash at the end does the reader know that it may be able to be left off of some URLs?

This author prefers ignoring a few normal rules of English in favor of extra clarity and maybe nobody noticed the lack of a sentence-ending period. Techniques the author prefers that work but may conflict with knuckle-slapping English teachers:

- Significant digits are especially important in technology. If the author writes 100.0 then be sure the final product also says 100.0 and not 100 or "one hundred".

- In the previous example, perhaps there should be a comma after the 100.0 in each instance. Because commas can also delineate multiples of thousands, unless absolutely critical suppress its use so close to numbers.

- Use special fonts, typically a fixed-spaced font like Courier (rather than proportional font like Verdana) for computer-sort-of things like:
     Web site addresses, URLs  ( http://www.strategysanity.com/style.html   http://192.168.0.1 )
     Filenames and path names ( C:\My_Documents\Webthings\reminders.docx )
The special font may get "neutralized" by a browser or downstream software but at least it's an attempt to give a unique look to just the text that needs to be typed in exactly.
Putting the exact text on its own line
  http://192.168.0.1
also makes it clearer. Remember that an underline, especially in blue, often indicates a live link and may hide a real underscore between words.

- Sometimes it may be best to leave off the period ending a sentence but instead just use a few extra spaces or maybe a carriage return. This is usually best when there are decimal points or "dots" of computer lingo essentially at the end of the sentence. Omitting the period keeps one extra dot or decimal from creeping into the subject.

- Commas should be used as thousands separators in numbers to aid readability, even for decimal numbers like 30,849.82 or just "4-digit" numbers like 2,500. The appending of a symbolic multiplier like the "K" in 2,500 K should not dissuade a writer from using comma delimiters. Commas in numbers, even columns of numbers, provide a visual clue to distinguish or emphasize scale, making numbers easier for the reader to absorb.

- An exception to the use of commas in numbers exists when those numbers represent computer programs and possibly the data being shown in computer programs. There, the programmers (people) who read or write the code are likely to be more used to seeing numbers, data, or instruction representations in specific ways, possibly with a space between every 4 or 8 digits, possibly in binary, octal, or hexadecimal representation. Also, in computer programs every character probably has a very explicit meaning, and a comma is more likely to separate options or whole variables rather than to simply provide visual guides to the human. Any stray punctuation in computer programs is a recipe for disaster, so keep commas in check there.

Hyphens, Commas:
Use them to improve readability of complex sentences.

Hyphens are helpful punctuation to connect words into more-complete thoughts. Do not be afraid to use hyphens in complex sentences. An out-of-the-box concept is easier to grasp than an out of the box concept because the four words together act as an adjective rather than a prepositional phrase.

Hyphens also link words that might be confusing or even wrong if the reader associates words incorrectly. For instance, in the earlier sentence

     "Hyphens are helpful punctuation to connect words into more-complete thoughts."

a hyphen assures that "more" links only with "complete", because the idea is not to make more thoughts, but to make the thoughts more complete. Complex technical or marketing sentences often feature strings of adjectives before nouns that work better with hyphens. While the order of adjectives plays a part, it is very helpful to the reader if hyphens connect multiplying adjectives.

On the other hand, the use of commas should be embraced and not forgotten. Commas place pauses in complex sentences to indicate the boundaries of partial thoughts. The idea behind all punctuation is to help the reader to grasp the meaning of the sentence quickly, without having to mentally break down and re-read the sentence. One good way to place commas is to consider reading the sentence aloud and place a comma where natural pauses in the sentence add emphasis or clarify the meaning; however, care must be taken when using this technique to avoid an overabundance of commas.

8-bit MCUs: Demonstrating many issues starting a sentence.

8-bit MCUs are microcontrollers that are probably the most basic computing circuit in use today. Starting a sentence with "8-bit MCUs" may epitomize a number of the issues discussed above. Starting a sentence by writing out the number eight would make the designation "8-bit" virtually disappear to the target reading audience so it is better left as a numeral. The hyphen is necessary to tie the number to the word "bit" so we know there are 8 bits rather than 8 MCUs (either one is possible). There are times in a sentence which is arranged differently where no hyphen would be used, such as in: The most popular word width of an MCU is 8 bits. Because eight was not written out, should there be a capitalization somewhere to indicate the start of the sentence?

Capitalizing "bit" has the same effect as writing out the eight, that is, it disturbs the pattern the reader is so familiar with.  Therefore, it is best to simply keep the hyphenated "bit" in lower-case. This is not to say all uses of "bit" should be lower-case.  The following sentence, caption, or even title should use an initial cap in the word "bit": 16 Bits Greatly Extend the Usability of an MCU. Here a hyphen after the number would have been wrong and its absence emphasizes the actual point of the sentence - that more bits are better.

MCUs is an abbreviation for microcontrollers. It would be quite suitable to start the sentence "8-bit Microcontrollers..." and here capitalizing microcontrollers is correct. If MCU has already been defined as short for microcontroller in the writing, then the better way to show plural of the abbreviation is to append a lower-case "s" to MCU rather than an upper-case letter. This highlights the plurality without making the reader wonder if S stands for "system" as it might in some abbreviations, and it also aids in reading aloud where the proper speaking of the letters would be saying "em-sea-ewes".

Etc.

A few other notes on use of words in English can be found in the Glossary under etc. for shortened Latin phrases, and certain quantity labels like B, G, K, M (sometimes with careful note of capitalization) and symbols and Greek letters (at the beginning of the Glossary).  

It's its: Special apostrophe in ownership, only with it.

An apostrophe (' or ´) can show missing letters when used to shorten (barely) contractions which are common in speech, such as "don't" or to show possession as in "Susan's house". With the word "it", an apostrophe is only used to show missing letters, as in the contraction for "it is" or "it has" which would become "it's". However, if a company used a brand name, one might write about the company, saying "its brand..." with no apostrophe between the t and the s. Note that a company is an "it", an object, not a "they", a person or persons. This is common English. Also, note that most corporations do not like an 's (apostrophe-s) appended to the corporate name to show possession, as an author may write in "Intel's Xeon processors...", but maybe should re-word as "Xeon processors from Intel...".