Direction for Your Business
While generally the formal rules of grammar, sentence structure, spelling, and writing style in the English (or American-
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-
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 come in various forms from formal to short-
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-
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-
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-
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-
Note that hyphenated numbers can be especially tricky, as noted later in this piece.
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-
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-
Web site addresses, URLs (
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
also makes it clearer. Remember that an underline, especially in blue, often indicates a live link and may hide a real underscore between words.
Hyphens are helpful punctuation to connect words into more-
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-
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-
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-
MCUs is an abbreviation for microcontrollers. It would be quite suitable to start the sentence "8-
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).
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.