Great Technical Writing Banish These Two Attitudes
Below is a MRR and PLR article in category Writing Speaking -> subcategory Writing.
Great Technical Writing: Overcoming Common Pitfalls
Incomplete user documents are a common disappointment for readers. Two prevalent attitudes among technical writers often lead to this shortcoming:
- "Everyone Knows That"
- "The User Can Figure It Out"
This article explores these attitudes and provides strategies to address them, resulting in more effective documents and happier users.
1. The "Everyone Knows That" Attitude
Assuming that everyone is already familiar with certain information can lead to gaps in understanding for your readers.
Consider This:
Do you know how to properly store tomatoes? Many people keep them in the refrigerator, which actually diminishes their taste and nutrition. They should be stored on a counter at room temperature until cut. Is this common knowledge? What assumptions are you making about your product?
Even common practices like shutting off a barbecue safely may not be as universally known as assumed. Many user documents cover this, but it's not always emphasized.
What's obvious to you may not be to others. For instance, how should one use a 2-in-1 shampoo and conditioner? Do you rinse it quickly or let it sit? Assuming "everyone knows" can lead to omissions in your document.
Tip: If you’re unsure whether something is widely known, err on the side of caution:
- Include an explanation.
- Direct readers to more information.
Another Tip: Don’t assume readers will remember details from earlier sections. Not everyone reads documentation in sequence.
Try This:
Consider how often you read a product manual from start to finish. If you do, ask others. This reading pattern allows for flexibility in writing and formatting.
2. The "The User Can Figure It Out" Attitude
Readers don't want to solve mysteries; they want clear, direct information.
When users engage with your document, they are trying to fulfill a need. Your product might be central to you, but to them, it’s a tool.
Example:
An email instructs you to call someone but doesn’t include the phone number. You’re left to find it yourself. This oversight is costly when multiplied across a company.
Consider date formats: "07/11/04" is ambiguous. Is it November 4, July 11, or April 7? Cultural differences in date formats can lead to confusion. This illustrates both problematic attitudes:
- "Everyone knows that" (assuming a standard format)
- "The user can figure it out" (by guessing based on context)
Don’t leave users to figure things out on their own. Add the necessary material. It only takes a moment and saves users a lot of time.
Action Steps:
The writing literature advises: "Know your reader." Apply this knowledge to improve your writing.
- Find someone like your target reader.
- Or, simulate being your reader the best you can.
Evaluate the Document For:
- Assumptions that "everyone knows that"
- Expectations that users should "figure it out"
- Unclear transitions
- Assumptions that readers remember the entire document
Revise These Sections:
A few additional words or sentences can make a significant difference. Your users will appreciate it.
You can find the original non-AI version of this article here: Great Technical Writing Banish These Two Attitudes.
You can browse and read all the articles for free. If you want to use them and get PLR and MRR rights, you need to buy the pack. Learn more about this pack of over 100 000 MRR and PLR articles.