Matters of Style
Technical Writer Uses 'Utilize' Instead of 'Use'; Readers Lose Will to Live
Even technical prose doesn't have to be a blunt axe when it could be an instrument of precision. Here are the style rules that separate professional documentation from amateur hour.
The Style Commandments
1Avoid Big Words
Never use a complex word when a simple one will do. "Utilize" is not fancier than "use"—it's just longer.
2Don't Use Contractions
In technical writing, write "do not" instead of "don't", "it is" instead of "it's". Contractions are informal and can cause confusion with possessives.
3Use "Can" Carefully
"Can" means ability. "May" means permission. "Could" implies uncertainty. Be precise about what you mean.
✓ "The function can process 1000 records per second." (ability)
✓ "Users may override the default settings." (permission)
4Avoid the First Person
Technical writing should be objective. Avoid "I think" or "we believe." State facts, not opinions. The reader doesn't care what you think—they want to know what IS.
5Use "If" Correctly
"If" is for conditions. "Whether" is for alternatives. Don't confuse them.
✓ "If the file exists, open it." (condition)
✓ "Check whether the file exists." (alternative)
❌ "Check if the file exists." (incorrect)
6Be Consistent
Pick a style and stick with it. If you call it a "dialog box" once, don't call it a "dialogue" or "popup" later. Consistency reduces cognitive load.
More Style Commandments
7The "It's" vs "Its" Conundrum
"It's" is a contraction of "it is.""Its" is the possessive form. When in doubt, expand it.
✓ "The function returns its value." (possessive)
✓ "It is important to validate input." (write it out!)
❌ "It's return value is null." (wrong!)
8The "A" vs "An" Rule (It's About Sound)
Use "an" before vowel sounds, not vowel letters.
✓ "An HTTP request" (H sounds like "aitch")
✓ "A URL" (sounds like "yoo-are-ell")
✓ "An SQL query" (sounds like "ess-cue-ell")
9The Ego Trip: Never Use "I"
The word "I" is anathema in technical writing. You are dealing with objective facts, not personal opinions.
❌ "I think this function should be called first."
✓ "This function should be called first."
Editor's Pet Peeves: Grammar & Logic
Spelling & Terminology Conventions
backward, toward, forward — No "s"
back up (verb) vs backup (noun)
set up (verb) vs setup (noun)
log in (verb) vs login (noun)
email — No hyphen
filename — One word
home page — Two words
Internet (uppercase)
KB (kilobyte) vs Kb (kilobit)
up-to-date — Always hyphenated
Quick Check
Which sentence follows technical writing best practices?