As a successful business owner, you probably need to prepare a wide assortment of documents, including proposals, user guides, instructions, and technical manuals. In addition to materials for clients or potential clients, you may need to document internal policies and procedures as part of your disaster recovery plan or risk assessment, new-employee onboarding, and more.
Most people simply cannot handle all of their company’s business activities on their own. Even if you are an expert on every facet of your organization, it involves a lot of time that you probably don’t have. The solution: you pay other people to help. You hire an employee or outsource certain work, such as accounting or software development, to specialists. However, if you’re like most business owners, you probably don’t hire a professional writer. You do the writing yourself, or you assign it to an internal technical expert.
Why is this? Just about everybody knows how to write—whether they’re good at it or not—so the decision to buckle down and do it yourself does make a certain amount of sense. Still, you probably don’t do your own writing because you’re an excellent writer or because you love writing. Even if you are excellent and you do love it, you undoubtedly have other things to do with your time. You may write your company’s materials yourself (or have an internal subject matter expert do it) because it seems too complicated or time consuming to share the information with someone else to write for you. Perhaps you’ve just never thought of using a professional writer.
No matter what your reason, the right technical writer can add value to your business and increase your profits by presenting your company in the best light possible. In this post, I will discuss some of the most common issues found in materials written by non-writers and how a technical writer can help.
Common Writing Problems
Some of the most common writing problems found in technical documents include writing for the wrong audience, using “technicalese,” organizational issues, poor presentation, and inaccurate information.
Writing for the Wrong Audience
Written communication is most effective when it is targeted and personal. That means that documents should always be built around the needs, interests, and desires of the intended audience.
Unfortunately, experts in most fields have trouble explaining the specialized concepts they know so well to non-experts. Their familiarity with a concept makes it difficult for them to recognize what is and is not common knowledge to others. They can also mistakenly talk down to an audience that may understand the concepts but not the terminology.Content written for the wrong audience regularly contains some of the following problems:
- Too many, too few, or the wrong details
- Unsuitable language—industry jargon or technical terminology
- Wrong language level—too high or unnecessarily simplified
- Prior knowledge assumptions—inadvertently overestimating/underestimating audience knowledge
- Irrelevant/inappropriate information—not addressing the reader’s questions
Given these difficulties, technical writers can be exceptionally useful. They will be able to ask the subject matter experts intelligent questions, gather relevant insights, and provide the information readers want with sufficient detail, at the right language level.
Frequently, technical documents are filled with language that is more complex than necessary and more difficult than the concepts they are communicating. These documents are overloaded with jargon, clichés, passive sentences, and an excess of adjectives that make the information they are communicating difficult to comprehend.
Technical writers can help eliminate these issues by finding the right balance in language. Readers are more likely to be receptive to a concept or proposal when it uses familiar language (e.g., terminology frequently used within their company or for their work). That means that some jargon and technical language—words commonly used and understood by the audience—is desirable. However, overuse of technical terminology or the use of unfamiliar jargon may not only confuse the reader but may also give the impression that your company is more focused on itself than its clients.Technical writers know how to:
- Avoid jargon, only using technical terms when necessary or appropriate for the audience
- Write simply, avoiding unnecessary words, sentences, and paragraphs
- Make text concise and straightforward
- Use the active voice to make writing more comprehensible and direct (see my last blog post for a discussion of the active/passive voice)
To communicate successfully technical writing must be well organized at every level, from the details of grammar to the structure of paragraphs and the outline of structural headings. Information can be complete and accurate, but if it is disorganized readers may misunderstand your point or be unable to find the information they need.
Content in technical documents is often poorly organized. Frequently, sentences within paragraphs and paragraphs within sections are arranged illogically or confusingly. Other times, the stated arrangement doesn’t match the actual arrangement. For example, the introductory paragraph may say that the document will cover topics A, B, and C, while it actually covers topics B, A, D, and C. This organizational issue is worsened when paragraphs are not written well, and a paragraph’s subject matter is not entirely clear.
Sometimes technical documents are well organized but lack a transparent structure and tools for accessing information. They may not have clear headings or a consistent numbering system. Or perhaps their tables of contents or indexes are inaccurate, incomplete, or non-existent. These documents may contain valuable information, but when readers can’t find what they’re looking for, it is of little benefit.
Technical writers are aware that poor organization stems from poor planning. Before they write, they plan. They create structural outlines that guide the document’s development and provide organizational clarity and transparency. They are also skilled at arranging information in the manner required by the audience or document type. They know, for example, that a technical proposal should adhere to the organizational parameters prescribed in the proposal request (RFP). On the other hand, they recognize that in step-by-step instructions, a “note” at the end containing information needed in the beginning can both frustrate the reader and potentially cause a problem.
Technical writers also know how to use their word processing tools expertly. They create headers, image captions, tables, and numbering styles in a manner that saves time and ensures consistency. The formatting they use enables them to make quick and easy global changes and create instantaneous tables of contents, tables of figures, and indexes.
“Poor presentation” is a catch-all category for a variety of issues often found in technical writing such as ambiguity and overuse of narrative paragraphs. The central issue with the problems in this category is that they make content harder to understand and dilute your message.
When a sentence is ambiguous it can be unclear who is doing what, or what is being described. Passive sentences frequently cause ambiguity. Consider, for instance, an assembly manual containing the following statement: “The bolt is attached on the left side.” In this example, it is unclear if the statement is describing where readers should attach the bolt or informing them of the bolt’s location.
Poorly chosen word variation can also cause ambiguity and confusion. While avoiding excessive repetition of certain words or phrases is a standard approach to good writing, it is not always recommended in technical writing. Sometimes, varying the words you use to describe important concepts can confuse readers. For example, when you refer to your product as a “software solution” but occasionally refer to it as “the application,” the reader may think you’re talking about something different.
A final issue in this category is the overuse of narrative paragraphs. Sometimes the best way to present technical material is with lists, tables, diagrams, and other alternatives. These options give the eyes a break by creating much-needed white space on the page and allowing rapid scanning. They also deliver information in a format that is precise and to the point. It is important to recognize the type of information you’re handling and communicate it in whatever manner is easiest to follow for your audience.
Nothing is more stressful for a business owner than discovering that the company’s technical documents contain factual errors—key details left out, improperly entered data, out-of-date information, etc. Of course, you know the correct information; the problem is finding the time to scrutinize your documents and ensure that everything is accurate and up to date. Technical writers have the time and the focus to help keep your documents accurate.
How Can A Technical Writer Help?The bottom line: a skilled, experienced technical writer can help you produce technical documents that communicate clearly and effectively. Here are just a few of the ways a technical writer can assist you with your technical communications:
- Planning and Management
- Identify what documents you need (both external and internal)
- Determine how best to organize and produce them
- Estimate time required
- Organization of Material
- Tailor the document’s structure and the level of detail for the intended audience
- Creation of templates for technical experts to complete
- Structuring of document outline
- Preparation of questions for technical experts to answer
- Document Development
If you have any questions or think you could use the services of a technical writer, get in touch. I’m here whenever you need me.
- Create content, rewrite and edit existing material
- Gather necessary information from your subject matter experts
- Communicate information accurately
- Develop tables and charts