Extending UML to the Documentation World—Using Process Maps to Create Task-Based Information

Home/Publications/Best Practices Newsletter/2005 – Best Practices Newsletter/Extending UML to the Documentation World—Using Process Maps to Create Task-Based Information


April 2005

Extending UML to the Documentation World—Using Process Maps to Create Task-Based Information

CIDMIconNewsletter Liz Stauffer and Joan Smith, Ultimate Software

The downside of a rapidly growing customer base at Ultimate Software (US) is the potential for an increase in the number of customer support calls and the resulting cost these calls could incur. To help stem the growth of the number of support calls, upper management at US looked to those of us who create and manage information for solutions. They believe that if customers are drawn to an online, user-friendly information system as the first source to getting their questions answered, the result will be fewer customer support calls and lower costs. The US Documentation Team had a mission.

Changing Our Way of Thinking

For several years, the US Documentation Team’s challenge had been to decrease the cost of the manuals we produced. To accomplish this, we transitioned over a three-year period from delivering printed and bound books with each release to “online guides,” created with RoboHelp and delivered on a CD with each release, to online guides delivered on the web and updated on an as-needed basis. These efforts were successful at decreasing the cost of the documentation while improving our return on investment and the business’ bottom line. Customers liked the changes as well and told us so. Since we had been successful at fulfilling the goal set for us, upper management was ready for us to step up to the next challenge and was confident that we would succeed.

To meet this new challenge, the Documentation Team needed to change the way it had been thinking. Instead of focusing on how we deliver the information, we needed to take a closer look at the content we deliver to determine if it was as good as it could be. We asked our customers if we were providing the information they needed to get their jobs done. The answers were mixed so we decided to look further into this question. To do this, we created the “Library Analysis Project.” Volunteers within the department formed a team to define a vision, purpose, and work agreement for the project. It was decided that the deliverable from the project would be a task analysis of the existing UltiPro Library and an assessment of the usability of the content. Before long, each member of the US Documentation Team became involved in the project in some way.

After the vision statement was confirmed and a work agreement formed, a project plan was built to define the project objectives, the resource requirements, methods for communication, team member responsibilities, and success criteria. An issues list and a risk mitigation plan were also defined. The project lead began `journaling’ the project; making note of both high- and low-lights of the project, including the successes, failures, and working relationships. This journal provides a chronological history of the project.

When the team began the analysis, they suspected that many of the tasks and procedures that we were writing and delivering to our customers were based on the user interface of the UltiPro tool. While these tasks were valid, they were not being expressed in a language natural to our users. So the first step of the project was to understand what information customers need to do their jobs independent of the software tool. We wanted to identify user tasks in a language customers use and understand. To guarantee customer success, we believed we needed to build an information system that would answer the questions customers asked. To be able to do this, we needed be able to anticipate those questions.

While we quickly confirmed that our initial assessment was accurate-our current documentation is often based on the interface to the software rather than user tasks-we still needed to come up with a way to verify the user tasks. During the last several years, US’s development organization has moved toward the use of modeling and other agile techniques to build the UltiPro software. Members of the Documentation Team had been involved in this process. We had attended training classes with the product analysts and the developers and had been introduced to modeling techniques used to design software. In an earlier workshop, we created an actor map to define the users of the information system and had worked with the analysts to develop and verify use cases. We liked the idea of modeling and thought we might be able to use modeling to help us define user tasks. We brainstormed on how we could extend the models being used in the other parts of the development organization to the information analysis project. The idea of the process map took root.

Our first attempts at modeling were crude. We took marker to white board and drew some squares and lines that represented processes and relationships between the processes. When we didn’t have a white board handy, we modeled on notebook paper. While we liked the informal nature of modeling our ideas on white boards or scraps of paper, we soon realized that hand drawings were inflexible and sometimes cumbersome. Revisions were awkward and erasing or crossing out lines could be time-consuming and messy. So we started using poster boards and sticky notes, which helped us to evolve to the next level of modeling. As our maps began to mature in detail and substance, we found that we could easily move the pieces around on the poster board during process map brainstorming meetings and, when needed, we could grab a different color to define an additional information type or rewrite an idea and place it elsewhere on the board (See Figure 1).

April 0530

Modeling helped us in another way. When we started to think visually, it became easier to ask the questions we needed to ask to help us identify the tasks our customers need to do to get their job done. Knowing this, we reviewed our existing guides, pulled out the `task’ portion of the information, and then started to think like one of our customers. We asked questions such as: “What do human resources administrators need to have in place before a new employee is hired (or an existing employee is terminated)?”, “What do payroll processors need to do to complete running a payroll?”, and “What system table information do system administrators need to set up security?” We were on our way to defining task-based information.

Over the next six months, we continued to mature the process map model as we used it to analyze information and build user tasks. We extended the models being used within our development organization with elements unique to information systems. The process map has components of an actor map, a use case, and a sequence diagram and it uses vocabulary from information mapping and content management. We built a glossary for the model so that we would use terms consistently within and outside our team. This became more important when we started to use the process maps as a communication tool with product management, quality assurance, and education services, among others.

Online Templates Created

As we became more sophisticated at analyzing information, it became more important that we standardize the process map and put it in a form that we could use for communication. To do this, we researched flowchart standards. Although a web search on “flowcharts” produced lots of hits for the topic, most of the results were geared toward flowcharting technical processes in software development and engineering, not the flow of information in a documentation deliverable. We knew we had to adapt. We borrowed the flowchart symbols used for the technical processes and altered them for the process maps. We assigned an information type to each symbol (prerequisite process, process, task, related information, and so on) and each shape. For example, a rounded-edge square represented a prerequisite process, a circle represented a process, and a rectangle represented a task. We created a set of standards for using the flowchart symbols and got started moving the process maps online. After some experimenting, we chose Microsoft Visio as the tool. Once we moved the process maps online, we found that it was easier to refine and add depth to them (See Figure 2).

April 0531

How We Are Finding Modeling Useful

Once the team fully embraced the concept of process mapping, we quickly saw the writers, the product analysts, and others start “thinking out of the box” as they worked on the maps. As we’ve become more creative, we’ve been able to identify and add relationships among the tasks, supporting information, frequently asked questions, and troubleshooting information to the maps.

Modeling has also helped us to see new ways to package and deliver information. For example, we are planning to remove the field level descriptions which had been clogging up the user manuals and move them into a field-level dictionary. We’ve centralized troubleshooting and error message information and have created a process and task map of the product. All of these moves have been highly successful with customers because they have helped us to streamline the guides. We believe this work will also help us transition to a single-sourced database solution in the future.

The process map has proven to be a highly effective quality assurance tool within Ultimate Software. We talk to our reviewers (product analysts, QA, and education services) on a new level. Instead of asking them to review our books, we have them review the process maps with us. Once we know the maps are accurate and complete, we have a high level of confidence that the information we build from them will be complete.

Next Steps

We have almost completed the analysis portion of the Library Analysis Project. The information architecture is in place and our process map library is continuing to grow. From here, we will start translating the process maps into content units or “chunks” that will be managed in a web-based Center of Information. We plan to build checklists, quick reference materials, and dashboards from these chunks. In some cases, we may even use the process map itself as the front end to a deliverable. As our development organization moves to more innovative and creative solutions for our product, we feel we will be in a position in the documentation department to support the product with a new and innovative information system.

We have an auxiliary project to design an interface to the Center of Information web site, and we’re using agile techniques, such as workshops and paper prototyping, to identify the requirements and create the preliminary design for this web site. Our goal is to go live with the first phase of the Center of Information in 2005. Upper management at US is highly supportive of our efforts and has expressed their confidence in us as we move towards delivering an information system that will serve as the front line to meeting the customer’s information needs. CIDMIconNewsletter

About the Authors

April 0516April 0529