We have covered almost all the steps involved in creating web based user documentation in the post series. But none of the products or projects are complete without the required quality checks. User documentation quality rests on multiple factors including information design and organization, the quality of information, and the functional interface. Almost all applications are now developed for multiple operating systems and mobile devices. Publishing information in formats suitable for each medium becomes a necessity rather than value addition. In this post, we will look at how we can ensure documentation quality and publish to various formats from a single source.
While it is easy to check the quality of a physical part using quantitative methods, documentation quality is subjective. If we follow the software quality mantra, all we need to worry about is conformance to requirements. However, technical writers rarely ever get a requirements document that defines specific requirements such as ‘ X tasks for this dialog box should be documented’. In this post we will look at what quality checks, if any, can we automate and the WordPress plugins we can use to test the user documentation.
Although it is not possible to automatically check if the content is technically accurate, we can use tools to check if the content is grammatically and syntactically correct. The ‘After The Deadline’ plugin highlights grammar and semantically incorrect word usage.
Similarly, Proofbot, provides multiple style options that you can define to check grammar and style. This is a paid service, but you might want to use this if you do not have a full-time editor.
You will rarely create user documentation that is completely without images and diagrams. When you create images, it is important that these images are legible and follow a guideline that you have defined. Additionally, your Web Help layout and the theme may dictate certain size rules that you need to follow.
Hyperlinks are one of the most beneficial features of online documentation. Links provide the users ready reference to additional information that they may not know and need to finish a task. However, a single incorrect alphabet or digit can block the page access. With large document sets where you have many in-line links and navigational links, checking each link becomes a tedious manual process. Although this link checker cannot certify that the linked page is the page that is supposed to open, it can scout for any damaged links in the documentation set.
Most of the software function on different operating systems and need some customized instructions. Similarly, user preferences also dictate your publication needs. Although this number is dwindling, you might be one of the few who distribute a printed book to your customers.
Kalin’s PDF Creation Station allows you to generate a PDF output of your WebHelp. With the available settings, you can define the structure of each page such as the elements you want in the page header, footer, the font of the text, and how you want to process the images and videos embedded in your Web Help.
You can also choose the topics you want to include or exclude and the order of the topics in the PDF file.
Mobile device Format
Most applications are now developed not only to work on various operating systems, but also on multiple mobile devices. Similarly, users increasingly use various devices to access information. In this scenario, it is important that you publish documentation that is compatible with multiple devices. The wp2epub plugin converts your WebHelp to epub format with a single click. You can also choose not to publish the entire documentation set to this format. For example, if your mobile application interface is different than the desktop application or has only limited features, you would want to include topics that are relevant only to that interface. I have not tested this on a mobile device, but this is how it looks on a ePub reader.
This concludes our Web Help with WordPress post series. Please comment and let us know if this was helpful and the things that we missed. Your contribution can help us all develop better documentation and tools for small businesses and start-ups for whom lower input costs are always desirable. We would also like to thank our regular readers for visiting our blog and encouraging us to complete this post series.