As a way of introducing the tasks and skills involved in creating technical communication products, MastersinCommunications.com interviewed professionals in the field regarding a project they took part in. Below are the steps they used to develop their product.
Identify Goals, Audience, and Scope
In an effort to improve functionality and effectiveness, a state agency hired a contract technical writer to design an online help tool to assist staff members in learning and using a new software system. She was tasked with:
- recommending online help software that would integrate into the new system;
- working with the staff members in each of the agency departments to understand how they would be using the system in order to design the help around their needs; and
- assisting the usability specialist who was hired to ensure that each module of the system would work without major problems before the next module was integrated and brought online.
The technical writer was an integral part of the transition team. In addition to creating the online help tool, she was also responsible for presenting updates and recommendations at weekly team meetings as well as quarterly board meetings.
Strategy, Planning, and Research
Each module of the online help tool was designed in three phases: gathering information, developing content, and testing and editing.
The technical editor worked closely with each staff member, department by department, to learn the tasks associated with their position. The method she used was to shadow each staff member, watch them as they interacted with the new software, and ask clarifying questions as they showed her the various tasks they carried out. Her focus was to understand:
- the ‘pain points’ in their work flow;
- the most difficult thing others would have to figure out if that staff member were unavailable; and
- the institutional knowledge in the staff member’s head that had not been documented.
This situation put the staff under a great deal of pressure, as they were required to assist in the development of the new software system as well as the creation of the online help tool, all while to continuing to do their daily work. One of the strategies the technical writer used to defuse tense situations was to bring the attitude of “you know more than I do” to each interview, respecting each staff member’s time, suggestions, and knowledge.
Develop Content
The new software system was developed in phases, one module at a time, based on the discrete responsibilities of each department. This allowed the organization the opportunity to learn from their successes and challenges before moving on to the next module. It was also the basis for the structure of the online help tool, so the technical writer was able to use the modules as the foundation for her tasks.
In an effort to not be influenced by a “how we do things” attitude, the technical writer made a deliberate choice not to learn the previous software system.. This allowed her to offer suggestions and insight on how to use the new system more effectively and efficiently.
Based on everything she learned from observing and interviewing staff members, the technical writer developed step-by-step instructions for each work process, created illustrations and charts to assist the user, and included sidebars and callouts to highlight important information. Document design and layout was a significant part of the project; she designed the help tool to be easy to navigate visually through fonts, colors, and illustrations.
Test, Review, Revise
Before each module went online, there was significant user acceptance testing (UAT) so that the team of programmers could discover and fix as many bugs as possible before going live. UAT is also known as beta testing, in which the user of the end product uses a series of scripts developed by the usability specialist to test whether the software works correctly in all potential scenarios. Each module was tested multiple times until a clean version emerged.
In addition to testing the functionality of the software, the beta testing also included use of the online help tool for each module, making sure the information was clear, correct, and usable.
Production
After the software system was fully implemented, the online help tool continued as a ‘living document’ that was updated regularly by the technical writer as the primary users discovered what did and did not work. The implementation team decided that printing the content within the help tool would be designed to be deliberately difficult and discouraged, since it was a living document. The technical writer created a few cheat sheets, however, at the request of staff members, to keep on their desks as they mastered the system.
Evaluation of Product Effectiveness and Retention and Disposition (Revise, Archive, Destroy)
After new modules were developed, tested, and put online, previously existing modules had to be refined and adjusted, including the help tool. These changes were often initiated by staff members who discovered unexpected blockages to their work flow. A reporting system was developed by the usability specialist so that users could report issues and fixes could be tracked. After fixes were implemented by the software developers, the technical writer updated the help tool.
The online help tool was intended to remain available and functional for the life of the software system. After the development phase of the project, the technical writer was hired as a permanent employee in the role of Communication Officer and was responsible for ongoing updates.
Conclusion
An effective help system, whether online or paper-based, should tell users clearly and simply how to move from one step to the next. This may seem easy initially; however, it entails the use of a variety of skills including clear writing, editing, design and layout, and most important, the ability to listen and learn from others.
Additional Technical Communication Case Studies:
Mountain Bike Race Guide
In order to help riders navigate the logistical issues involved in an international mountain bike race, as well as the course itself, a technical writer and a usability tester research and develop a detailed guide to the event.
New Employee Training
This case study explores the creation of onboarding materials for new employees hired by a growing non-profit organization. It discusses scope and goals of the project, along with the skills needed to complete the training program.
