Strategies for Creating Effective Technical Documentation – Part 3

Posted on January 5, 2021 By Kalleid Blog

In part 2 of our blog series on creating effective technical documentation, we detailed a best practice methodology that ensures the documentation will maximize benefits for your organization (part 1).

[Read More]

Creating effective technical documents involves more than just applying a proven methodology, however. Good technical writers bring important skills and knowledge to their profession that have been acquired from years of work in the technical writing trenches. These skills are essential for applying the above methodology effectively. In this blog, we will describe several important technical writing tips for producing world-class technical documentation.

Writing Tips for Creating Effective Technical Documentation

Choose the right documentation type. The different types of technical documentation are virtually endless – user manuals, how to guides, reviews, reports, newsletters, presentations, web pages, proposals, fliers, memos, press releases, handbooks, installation guides, FAQs, release notes, help files, SOP documents, API documentation, style guides, user requirements specification, etc. One of the first things a technical writer needs to do is determine which type of document is most appropriate to meet the customer’s needs. A thorough audience assessment and task analysis is essential for this purpose.

• Audience assessment or user analysis – An assessment of the relevant characteristics and needs/goals of the intended audience, the users of the product, is important to inform the choice of document type. The results of an audience assessment should be included in the document plan.
• Task analysis – A task analysis determines which tasks are performed by users, along with key steps involved in completing those tasks. This information will help identify which tasks need to be documented, along with which type of document is most appropriate for this purpose. A task analysis is critical to create an outline for a deliverable or develop a set of online help topics. In addition, a thorough task analysis can help project managers define project scope.

Choose the right authoring tool. One of the most challenging aspects of becoming a good technical writer is learning how to use all the different authoring tools available. The technical writer must be strongly competent in many different authoring tools, because organizations will likely require the writer to use whatever tool is available. Authoring tools generally fall into one of five different categories:

• Desktop publishing – Standalone systems that live on PCs and allow technical writers to both author and publish; for example, Google Docs, Microsoft® Word®, Adobe® FrameMaker®, Adobe® RoboHelp®, Adobe® InDesign®. These tools are good for small teams and content that is not reused or published to multiple outputs.
• Structured authoring – These types of tools are basically text editors that can be used with a markup language live XML or DITA to tag content based on predefined set of rules (e.g., document type definition or DTD). Examples include Adobe FrameMaker, oXygen, XMetaL and ArborText. Structured authoring tools are good for larger teams creating content that will be reused and/or published to multiple outlets. Structured authoring is used in content management systems (CMSs) such as MadCap® Flare and Tridion products. CMSs are particularly valued for their XML output that is used by translation services.
• Help authoring tools (HATs) – These tools are designed to deliver online help to users. Some HATs like RoboHelp can also do desktop publishing. HAT tools are good for small teams and content that does not need to be translated or managed within the tool.
• API and developer documentation – API documentation is a rapidly growing niche within the technical writing profession, as many companies are finding that technical writers are better at creating this kind of documentation than software developers. Examples include Sphinx, Swagger, Slate, and Jekyll.
• All-in-one tools – these tools combine authoring, publishing and content management into a single tool such as Author-it, IXIASOFT, easyDITA. Good for large teams and medium-sized teams that lack large budgets or technical resources.

Be brief, yet thorough. After identifying users and tasks, practicing minimalism is perhaps the most important criterion for good technical writing. While fulfilling safety, compliance, and legal requirements, technical documents should contain only as much content as required for the user to perform a task, and not a word more. Readers of technical documents are typically busy people, and they expect documentation without repetitiveness, wordiness or redundancies. Give the audience the information when and where they need it. If necessary, appendices can provide supplementary material. Minimalist technical writing saves time and money.

Foster efficiency by topic-based authoring. Topic-based technical writing is a modular approach to creating content that is structured around topics, where each “topic” has an identifiable purpose (procedure, concept, reference) that does not require external context to understand. This type of authoring fosters efficiency in technical writing, as it allows the different modules to be mixed and reused in different contexts. Topic-based writing can streamline content, as minimalism dictates. Topics are also the backbone of component content management systems, where technical writers assemble topics into documents.

Practice task-oriented technical writing. Technical documentation helps the user perform a task that accomplishes real-world goals. As such, task-oriented writing that provides a workflow to do something is preferred over writing with a functional orientation. For technical writers, writing with a functional orientation (for example, systematically explaining each function, feature, or interface element of a product) is only appropriate in functional specifications and some SOPs. Functional writing can be a burden to the user. Every good technical writer is proficient at writing task-oriented topics.

Task-oriented writing requires a comprehensive task analysis prior to the start of the writing. Technical writers or marketing staff should interview users and observe what they do, an activity called contextual inquiry. Tasks can be discovered by reviewing voice-of-the-customer material from marketing and customer logs from technical support. After the tasks and workflows are defined, technical writers can then develop the documentation.

Use templates for consistent on-page design. Templates lock in structure and consistency. They are a good tool to plan documentation. For example, a template for a single-chapter protocol contains headings and boilerplate text:

• Title and document part number – What the document is about and how it is referenced including version number and date.
• Before you begin – Prerequisites to complete before performing a task.
• Materials required – All items needed to complete the task, usually tabulated with part numbers.
• Step-wise procedure – Numbered steps in a workflow. The steps also include notes. Notes format are included in the template.
• Graphics – Formats for diagrams, photographs, and tables to support the text.
• Read next – Related documents that the user may find useful.

Use visuals. Whenever possible, use pictures, diagrams, graphics, tables, and bulleted lists to visualize the content. Show, not tell. In addition to being an effective way to communicate information, visuals will help improve the readability of documentation by breaking up the monotony, length, and complexity of the text. The principle of minimalism applies to visuals for maximum impact and meaning.

Use examples. When trying to make a concept crystal clear, first verbally describe the concept, then add a visual illustration, and finally provide an example of the concept. Let’s apply this tip to an elementary algebraic concept.

• Verbal description: Pythagoras’ theorem is an equation in Euclidean geometry that relates to right triangles. The theorem states that the area of the square whose side is opposite the right angle (i.e., the hypotenuse) is equal to the sum of the areas of the squares on the other two sides.
• Illustration: Pythagorean Theorem 

   Example: In the diagram above, if a = 2 meters and b = 1.5 meters, then

c² = 2² + 1.5² = 4 + 2.25 = 6.25 meters²

Thus, c = √6.25 meters² = 2.5 meters

Conclusion

By following the methodology described in part 2 of this series, and the writing tips described in this blog, technical writers can develop complete technical documentation to meet the requirements of all stakeholders, including customers, marketing, regulatory, safety, legal, and QA. Successful technical documentation reduces training time and costs, builds company value, improves outsources, supports IT, and reduces the burden on customer support.

Many company executives and managers make the mistake of viewing technical documentation as something that just needs to get done in order to satisfy customer or regulatory agency demands. This can lead to a scenario where an organization tries to create technical documentation in-house when they do not have the expertise on staff to be successful. Unless there are good technical writers on staff, or engineers and/or developers with good technical writing skills, best practice is to outsource technical documentation to a qualified third-party consultant.

by Kalleid