In our August 22, 2014 post, we spoke about what technical writing managers, seeking to expand their departments, needed to look for to hire the best technical writers. In today’s blog, we’ll talk about what those writers will need to do and look for to make sure they produce documentation that’s user-friendly and follows the attributes of good technical documentation.
Plan before you begin
- Identify your audience
- Know the purpose of the document
- Identify all regulations and standards that must be followed
- Clarify all safety issues or concerns
- Confirm the style guide and terminology to be used
- Understand your role in the project
- Plan time to write, review, revise, and edit
- Know what the deliverables are and their assigned deadlines
- Identify members of the documentation team and their responsibilities
- Organize your resources and familiarize yourself with the attributes of good technical documentation
Attributes of good technical documentation
- Adheres to best practice standards
- Content is relevant and accurate
- Information is organized logically
- Content has a consistent style
- Format and layout is easy to scan and read
- Uses appropriate graphics and tables to support the text
- Uses keywords that enable content to be readily searched
- Includes all the information users need or might want to know about the topic
Attribution: Image used above is courtesy of imagerymajestic / freedigitalphotos.net.
6 Qualities Technical Documentation Needs to Make It User-Friendly
When we talk about technical documentation being user-friendly, we mean that the language and content in the document is compatible with the user’s ability to understand the information presented and to apply that information as intended. Documents that include the following qualities meet the criteria for being user-friendly:
- Clear. Writer uses short words and short sentences. All unique technical terminology is defined up front, and those terms are used consistently throughout the document to avoid confusion.
- Concise. Writer doesn’t use big words when little ones will do. Writer also uses words efficiently and to the point.
- Correct. Writer observes the conventions of grammar, spelling, punctuation, and usage. To do otherwise would distract the user and negate the importance of the document's message.
- Accurate. Writer makes sure that the content is true and that all procedures actually work as described. Writer works with the project's subject matter experts (SMEs) to validate the content and is aware that errors found in the document can cause users to doubt the validity of the entire document.
- Accessible. This refers to the ease with which users can locate the information they seek. Writer uses styles and tags during the document development process to create accessible documents.
- Complete. Writer makes sure that the technical document includes everything the user needs to be able to apply the information presented efficiently and effectively. Writer also uses peer review as a way to test if the presented information is complete.
Good technical documentation benefits both the company and the customer. For FDA-regulated companies, well-written and user-friendly documentation helps them meet compliance requirements faster. For all companies, regardless of their industry, it increases customer satisfaction, reduces complaints to customer support, and minimizes potential lawsuits, all of which reflects on the company’s bottom line.
How do you define user-friendly? Do the above qualities fulfill your idea of what makes for a user-friendly document? If not, what would you remove or add to this list? Share your thoughts in the comments below.