TechDocs Tips – Miller & Mattson

Following are some tips for technical documents that we have been sharing on Twitter #TechDocs.

While style guides differ, here’s the overarching rule: If you choose to commit a grammatical or typographical sin, then sin boldly and consistently!

The TechDocs Tips, by category

Math and numbers

Don’t avoid your word processor’s equation editor out of laziness. Your equation editor will produce a higher quality result than other solutions.
A space goes between the number and the unit of measure: 1.0 mV, 120 mm.
There are several ways to indicate a range: an en dash (1–10), words (1 through 10), two or three dots (1..10), or brackets [0,10]. Any of these notations will work if used consistently in a document.
The prefix for “micro” (one millionth) is a Greek mu (μ), not a Latin u.
Mathematical exponentiation is often represented either by superscript (2³²) or with the caret symbol as it appears in software source code (2^32). Better to use superscripts except when it appears explicitly as source code.

— Back to the Top —

Punctuation

Use en dashes for ranges like A–Z. Use em dashes to set apart contrasting sentence parts—like this. Use hyphens to create stitched-together words.
If it’s an adjective, it needs a hyphen, otherwise, it doesn’t. For example: This 32-byte field is 32 bytes long.
Instead of “x” or “X” or “*” or even just a dot for multiplication, how about a real multiplication sign: “×” (Unicode U+00D7 or HTML entity ×).
Instead of a hyphen for a minus sign, try an en dash (–) or a real Unicode minus sign (−, Unicode U+2212 or HTML entity −).
If you’re typing on a typewriter with a fixed-space font, then end a sentence with a period and two spaces. Otherwise, only one space is needed after a period with a proportional-spaced font. (Extra tip: globally search for those double spaces that escaped detection.)
A slash has no universal interpretation. Don’t use/employ slashes when common words suffice. A slash often can be replaced with “and” or “or.”
Quotes can be used to emphasize terms. Don’t use them gratuitously because quotes also can imply that the “word” should be interpreted in a “different” way than it is normally understood.
It’s common to put double quotes around the names of articles and italicize the names of books.
If you need to enclose text in quotes, use a consistent style. Styled typographic or curly quotes (“like this”) are prettier than straight quotes ("like these"). Straight quotes are appropriate in software source code.
Series comma (Oxford comma) or not? Whatever butters your biscuit. Just be consistent (and be aware that this topic can start fistfights).
In American and international style, the comma usually goes inside the closing quotes, like “this.”
Most style guides prefer that you add a comma after the words “for example,” even when it’s abbreviated, e.g., like this. Same goes for “i.e.”
Set off explanatory text—like this example—with matching em dashes or matching commas. Commas are more subtle while em dashes emphasize contrast.
Rules differ for using spaces with dashes. Just be consistent.
Parenthetical text, if removed, should leave a grammatically correct sentence. “This sentence (the one you’re reading now) is an example.” → “This sentence is an example.”
Where to put the commas around a qualifying clause? When the clause and its surrounding punctuation are removed it should leave a correct sentence. Example: “This sentence, which is an example, is correct.” → “This sentence is correct.” Another example: “This sentence which, as another example, isn’t correct.”

— Back to the Top —

Grammar

Try each pronoun separately to see if it’s the right form. Example: “It will benefit you and I” (correct?) Try: “It will benefit you” (that’s correct); and “It will benefit I” (oops, wrong pronoun form. Try “me” instead).
The term “URL” is more often pronounced “you are ell” instead of “earl,” so the preferred indefinite article is “a” as in “a URL.”
“You and I” is a subject. “You and me” is an object. Example: “You and I need to talk about you and me.”
Don’t omit the customary definite and indefinite articles “the” and “a.” They make sentences smoother and easier to read.

— Back to the Top —

Word choice

Does the phrase “values from 23 to 25” include or exclude the 25? A specification document should clarify with “from 23 to 25 inclusive” or “from 23 through 25.”
For each technical concept or thing, choose one name and use it consistently. If it’s introduced as a ground braid, then don’t refer to it later as a ground wire.
It’s all too easy to confuse “its” and “it’s” because English is a crazy language. Without the apostrophe, it is possessive. With the apostrophe, it means “it is.”
It’s all too easy to confuse “then” and “than.” When comparing two things, use “than.” In most other cases, use “then.”
Use “fewer” for quantities expressed in integer amounts. Use “less” for non-integer quantities: fewer cookies, less fat, fewer people, less noise. It’s a questionable rule, but expected by many readers.
Idioms don’t always translate well. Avoid them if your writing may be read by someone who is not as familiar with the language as you are. Replace idioms with simple, clear words.
Replace the phrase “for all intents and purposes” with more direct words. Does it mean “always?” Or “for our needs?” Or “in effect?”
Replace the word “utilize” with “use” unless that’s not what you mean.
Reserve the term “sea change” for describing a metamorphosis such as in Shakespeare’s The Tempest, from where the term originates. Consider simplifying it to “change” if that’s what you mean.
Often you can replace the phrase “in the event that” with “if.”
Sometimes there is no good substitute for “and/or.” Avoid it in legalese, and use it in other contexts only when the sense is clear and after considering alternatives such as “A, B, or both,” or “A or B.”
When revising a phrase, try replacing a generic verb with a more descriptive or precise one. For example: “Heat will damage the material.” → “Heat will fracture the material.”
You can almost always replace the phrase “in regards to” with more direct words. Example: “The new version is an improvement in regards to speed” → “The new version is faster.”
“Different to” is common in the U.K. but sounds odd to some U.S. readers. “Different than” and “different from” work well for an international audience, although some pedants will object to either. Alternatively, rewrite using comparative words.
“Between zero and ten” is ambiguous (does it include ten? Or zero?). It’s clearer to say “between zero and ten inclusive” or “from zero through ten.”
Don’t use a long word if a shorter word works just as well. Usually “via” means “by,” “utilize” means “use,” “endeavor” means “try,” and “terminate” means “end.”
“Associated with” is more traditional and common than “associated to.”
“Straightforward” is one word.
Whenever you see the words “in terms of,” delete those words and say what those terms are. Example: “This is an improvement in terms of security.” → “This improves security.”
A specification document should contain sentences that are prescriptive rather than descriptive. Example: “The chamber pressure is less than 100 psi.” is descriptive. “The chamber pressure must never exceed 100 psi.” is prescriptive.
“Apropos” does not mean “appropriate.” It means “in reference to.” Because it’s a confusing word, replace it with more common words.
The word “via” is ostentatious if it means nothing more than “by” or “with.” Use the simpler word instead.
Convert passive voice into active. Example: The maximum speed is limited by a governor → A governor limits the maximum speed.

— Back to the Top —

Casing and spelling

The prefix “G” (giga or billion) and “M” (mega or million) are upper case. The prefix “k” (kilo or thousand) is lower case.
There’s no need to capitalize “byte” in a normal sentence.
It’s okay to title-case your section heads if you want to. Or don’t. Just be consistent within the same level of heads.
In normal sentences, capitalize common words only if they are components of a proper name. A “signal multiplexer” is just normal words, but “Acme Signal Multiplexer” might be a proper name.
In software and electronics documentation, pay attention to capitalization of variable names, pin names, and signal names. They are their official names and each one should be spelled and capitalized correctly.
Respect the spelling and casing of third party names and terminology. Investigate who invented a thing and named it. For examples, it’s JavaScript, Wi-Fi, LaTeX, and JPEG, not Javascript, wifi, Latex, or jpeg.

— Back to the Top —

Doc parts and style

An appendix should only contain text that can be omitted without damaging the integrity or coherence of the document.
Most technical documents need a well-stocked glossary and abbreviation list. Not at the end of the document, but right up there in the front matter.
Capitalize the words in your glossary as they should be capitalized in common usage—only the proper nouns should be capitalized.
Some organizations use full text justification because the pages look pretty at a distance if you squint. More often, organizations use ragged-right text because the long words often found in technical documentation work against full justification.
Underlining is for typewriters.
Don’t skimp on the document index. It might become the most-used part of the document.
Writing a long and complex document or email? Maybe add some headings.
Bulleted and numbered lists help the reader navigate a document. Number the list only if the order matters.
Wordy writing is lazy writing. Blaise Pascal once began a letter with “I have only made this letter longer because I have not had the time to make it shorter.”

— Back to the Top —

Abbreviations and acronyms

At the first appearance of a TLA (three-letter acronym) or other abbreviation, show its full form.
In normal sentences, there’s no need to abbreviate words such as info, 1st, Nov., and spec. Use your words: information, first, November, and specification.
Abbreviations for provinces, states, and other administrative divisions are only appropriate in postal addresses. In other contexts, spell out the place names.
Avoid Latin abbreviations. E.g., cf. Strunk and White op.cit. aff. MLA et al.

— Back to the Top —

Figures

Embed diagrams and charts in your document using a vector format so that they will display clearly at any zoom level. Raster formats won’t retain their sharpness when enlarged.
Try to make the text inside your diagrams and tables no smaller than one point smaller than the document paragraph font.
All the images in a document will look better if they have a similar contrast and brightness. Adjust individual images as necessary.

— Back to the Top —

Drafting and revising

When revising a sentence, first determine which noun is the main subject and which verb is its action. Compose a minimal sentence containing only the subject and its verb. Then insert the other nouns and verbs as qualifiers and objects.
Each paragraph should present only one main idea or concept. The first sentence of the paragraph should indicate what the paragraph is about.
Multiple simple sentences can be easier to read than one long, complex sentence.
Explain your point in narrative form. Read what you wrote out loud, at least in your own mind, and pretend it’s your Aunt Selma reading it. Will she understand what you intended to say?
When revising a difficult paragraph, first determine its main thesis. Rewrite that thesis as simply as you can, then add the necessary supporting points. If the thesis can’t be stated simply, it may need to be organized as multiple paragraphs.
Give your writing a rest overnight and read it again the next day with fresh eyes. You’ll often see ways to improve it.
Does the paragraph not sound right? Don’t be afraid to toss the whole thing and start over. The second attempt may be half as difficult and twice as good.
Backups. They’re worth the effort.
Every email message you write advertises your writing skills. Review what you just wrote before clicking Send.
For an international audience, split complex sentences into multiple simpler sentences. Use a reading level analyzer to measure the reading difficulty of your text.
When revising a sentence, see what happens if you move the subject and verb to the beginning of the sentence, then add the supporting clauses.
Value all feedback from reviewers. Positive feedback can give you confidence in what you’re already doing; negative feedback can make you a better writer.
The opening sentence of a paragraph should tell the reader where that paragraph is going. It can do so by summarizing, predicting a conclusion, or presenting a question or a thesis.
In many cases, a chapter or book can be organized like this: (1) tell them what you’re going to tell them; (2) tell them; (3) tell them what you told them.
A 2021 study found that technical papers containing higher proportions of jargon in their titles and abstracts were cited less frequently by other researchers. Replace some of that jargon with plain language.
In a technical specification, every specialized term should be clearly defined by narrative, by glossary, or by reference to another specification. A non-specialist reader can help identify the terms that need defining.
Pretend you are a member of your intended audience, then re-read what you just wrote. Can you revise the text to make the message clearer?
Get a good night’s sleep before editing the text you just wrote.
An effective technical proposal clearly defines the problem to solve and compares the consequences of applying or not applying the proposed solution.
If you allow plenty of time for researching and planning up front and time for editing at the end, then writing the draft should be easy.
Don’t know where to start? Develop a few main headings. Add some subheadings, then some sub-subheadings. Then add in some sentences like folding chocolate chips into cookie batter.
Try writing the conclusion first. That may illuminate how you need to start.
As you’re developing a complex document, frequently archive document revisions, especially when working with a fragile document format (*cough*MSWord).
Look for very long paragraphs that contain multiple points. It might be more effective to present each point in a separate paragraph.

— Back to the Top —

Advice for tech writers

Tech writers: ask to be included on the engineering mailing lists and issue trackers so you can get exposed to the terminology and concerns that you’re writing about.
Tech writers: research your client’s competition to learn how you can better position your client’s product.
Most word processors and text editors allow you to search for text using regular expressions. Learn how to use regular expressions—they make certain hard jobs easy.
When it’s time for a full-document review, assign specific sections of the document to specific reviewers so that you don’t overwhelm any one individual.
Choose a style guide, get familiar with it, and apply it consistently. Or write your own style guide. [Here’s the Miller & Mattson style guide.]
Know what audience you’re addressing. What is their background, reading level, and language proficiency? What are their concerns, hopes, fears, and biases?
Double check how you spelled and case your client’s name. Nothing is more dear to a person than their own name, so it pays to get it right.

— Back to the Top —