View Only

Beyond Just Documentation — Enabling Users in the Age of Digital Delivery

By Forest Weld posted Tue December 08, 2020 11:39 PM


In this age of modern software and the Internet, we have many means to quickly help users get done what they need to get done, even with complex, sophisticated software. Software-doc professionals have many tools to help make products intuitive and technical specifics quick to find. We have progressed beyond crafting clear and accurate explanations, beyond just writing manuals, and are now focused on quickly enabling users by having the right specifics at the user’s fingertips. 

First and foremost is for writers of software documentation to work with user-interface designers to make the interface itself as intuitive as it can possibly be — reduce the need to even go to the documentation. If a user task requires a long and complex explanation, the tech writer brings that use case to the UI designer so they can revisit the design and simplify in light of the user steps that were brought out by drafting the docs. 

And tech writers can work with the overall team to ensure that the text in the user interface is precise, accurate, and intuitive. A carefully chosen label on a box or button, or an added line of "helper text”, can make all the difference.

Opportunities for such clear and accurate “microcopy” abound: hovertext, log messages, error messages, and even API nomenclature and parameter names make a huge difference for users when the right, intuitive words are contributed by a professional tech writer integrated in the engineering team. 

Even longer written explanations can be engineered to provide users quick access to the right info. Careful architecting of information for the right user tasks, “chunking” that makes it easier for users to scan, illustrations, bulleted lists, advance organizers — and with today's tools we can build "progressive disclosure" of increasing detail right into the user interface, with an eventual link out to a specific explanation in the manual. 

And of course the user documentation can be integrated directly into the application — as in Aspera on Cloud’s Help Center — and can include quick intros to new features in a dynamically updated What's Newsection.

Documentation of REST APIs can be tied closely to the APIs themselves through Swagger/OAS, for accuracy and consistency, and can be complemented with hyperlinked explanations of key concepts, code examples, and integration architecture (as in IBM's API Explorer / API Hub). 

And perhaps the ultimate aid: interactive explanations with graphic pointers provided to the user step by step, right in the interface, leading them from screen to dialog box to task accomplishment — as through the Guided Tours button in Aspera on Cloud and in more and more IBM offerings.

We’re pursuing all these techniques within Aspera products and in other IBM products, in our effort to get users the quickest information most targeted at their needs and their job at hand. But the ingredient that makes these tools most effective is input from real users, so please let us know what information and in-app assistance you need to get the most out of your IBM Aspera investment. We’ll be watching for your comments below.