STS Blog

The Work Management Process is an initiative of one of our clients to standardize the process of work identification, planning, and completion at power plants the Company owns and operates. This process aims to transition work activities at power plants from a reactive to a planned mode, thereby improving asset reliability and lowering costs.

The purpose of this training is to present an overview of the Work Management Process either as a refresher for existing employees or as an introduction for new employees.

The training is broken down into six lessons, each of which correspond to a particular step within the Work Management “Wheel.”  Unlike a training course delivered via a learning management system, this training is completely open-ended so learners are free to explore and learn at their own pace.

Although this training is open-ended, some managers wanted their employees’ progress  to be tracked to test their mastery of the content.  Learners can directly link to a short quiz stored within an online learning management system from the Work Management Process Training site.

Goals and Objectives

The original Work Management Process Training existed as a 180-page document that learners had to read.  Once our Technical Communications project team got our hands on that, we all recognized that we had an opportunity to create a unique eLearning experience from this training.

The primary goal of the training site is to create an interactive, online resource that employees can visit to learn about the Work Management Process.  Using a simple design, contextual links and actions, drill-down exploration of content, and leveraging interactive learning experiences, our training site easily stands out as a technology-based learning site unlike any other training initiatives we have created in the past.

The objective of this training is to promote and encourage learners to “explore the content” rather than simply read it. Many learners have become too accustomed to reading through text-heavy documents and diagrams, which can detract from the learning experience. We set out to create an engaging and immersive learning experience that would change the way our employees viewed eLearning, and based on the positive feedback this training has generated within all levels of the company, we would like to think we have succeeded.

Design Theory

The graphical user interface for this training was developed progressively over the course of a series of design review sessions. In an effort to make this training the first of its kind for our client, we decided to use a bold UI design that would capture the learner’s attention and stand out in their minds from the typical text-heavy, online training modules that they have seen for the past decade. Pulling design theories from software user interfaces, our UI aims to make navigation intuitive, thus simplifying learner actions.

The Work Management Process Training was built by deploying custom code and content onto a Microsoft SharePoint site. Since SharePoint has the ability to integrate with many types of content, we found it advantageous to use it as the platform for our backend. The build process was relatively simple and straightforward — custom CSS code was applied to the existing SharePoint template and then an assorted set of content was added to each page, including Flash interactions, Captivate movies, and custom Javascript functionality.

Figure 1: The Work Planning lesson within the Work Management Process Training site

Our goal was to attain a clean and simple “web 2.0” visual style in this interface.  We achieved this through the marriage of custom code and graphics with the simplicity and flexibility offered by SharePoint. Through our modifications to the backend and our design of the user interface, we created a smooth and visually appealing interface.

Success through teamwork

One of the most successful elements of this project was the dynamic that our project team shared. With a small project team, we found that having a solid plan of attack would be paramount in making forward progress and meeting our deadlines. Before development began, we created a role-based division of labor which would allow us to work effectively in our areas of expertise.

Using this approach, we adapted an agile development method, focusing heavily on collaboration, constantly adapting our design. Throughout the project life-cycle we had at least one design meeting per week, and this allowed us to openly share our work, obtain feedback and criticism, and to brainstorm ways of approaching and overcoming various challenges. We set many short milestones for our team over the course of the project, typically lasting one to two weeks. After each milestone, we held a meeting to present and review our deliverables and determine if we needed to adapt our design to technical limitations, design flaws, or inconsistent learning experiences.

Technical challenges

With innovation comes technical challenges and creating this training had its share of obstacles. The first 3 months of this project were spent on rapid prototyping in Flash and SharePoint and for the remaining 6 months, we were in an agile development mode, constantly building and revising along the way. Most of the technical challenges came within the latter portion of the project life-cycle, as we were rethinking the designs used in our beta prototype. For example, one large challenge we faced was selecting how to best present the content of the training to the learners.

In our first prototype, we tried to make the content more aesthetically pleasing by turning it into a series of images which we turned into a slideshow using simple Flash interactions, but this method made it too difficult to edit the content and too difficult to maintain via Photoshop and Flash.

Figure 2: Content delivered through Flash in the beta prototype

The failures that we encountered throughout this project’s life-cycle only made it easier for us to adapt to the problem and find innovative solutions to bridge the next gap. In our next prototype, we took the content, dropped it into a PowerPoint presentation, and exported it as an MHTML file, which was then embedded within the SharePoint page. This method made it much easier for content maintenance and allowed our content to look however we wanted it to, but since the presentation was scaled down drastically to fit within the space we had, it was impractical for us to include any interactive elements.

Figure 3: An embedded PowerPoint presentation in the training site.

We spent a lot of time in design meetings discussing how to best approach this challenge and how to find a good middlegroud – we needed something that was easy to maintain yet visually appealing and allowed for interactivity.

Figure 4: The final lightbox version of how we display content.

In our final prototype, we achieved the balance of aesthetic and functionality by putting our content into a Captivate movie. We displayed the content in a series of slides, interspersed with quizzes, and also included other interactive elements to enhance the learning experience and boost retention. Additionally, to overcome the constraints of embedding the content directly into the SharePoint page, we built a “lightbox” by modifying third-party code, which could open a separate layer over the current site and play a Captivate movie, giving us the learner’s entire screen to display information.

An interactive approach

The Work Management Process itself has numerous process flow diagrams within it, since each part of the process has a series of steps that must be followed to complete it. Instead of simply placing the image of the process flow in the content on the training site, we thought that this would be a good opportunity to use interactivity to bring a static image to life.

Figure 5: The Process Flow Viewer promotes learning through interactive, drill-down learning.

After many prototypes and putting a lot of thought into both the interactive design and the instructional design, we created the “process flow viewer.” This interactive process flow takes the simple image of the process flow and lets the learner overlay information on top of it, such as what steps of the process flow apply to them based on their job role. This activity also allows learners to engage in drill down learning – each step within the process flow can be clicked to learn more about that step in detail. Learners can also play a simulated walkthrough of the process flow, allowing them to see the process flow in action.

The process flow viewer can be launched from the menu of a lesson or while viewing the content itself.  In both cases, it launches in a separate window so as to not interrupt the main navigation, allowing learners to view the content and the process flow side-by-side if they are using a dual monitor setup.

Tell Someone About This Post:

Aberdeen Group completed a study earlier this year that indicates when technical communications are approached strategically, companies provide significant customer-facing value. – David Houlihan, Senior Research with Aberdeen’s Product Innovation and Engineering Practice.

What does this mean for technical documentation departments and companies? It means that companies researching, authoring, and producing technical communications need to focus on pertinent data which consumers will actually use. When people comment on the entity that is technical documentation, they use the words “concise” and “practical.” Why does the majority of technical documentation fail to follow these expectations? One of the many problems with technical documentation is that it very rarely uses orality. Many of you might be considering, “Orality? What does that mean?” It means that technical documentation is not written as one would speak which further alienates consumers from ideas and communications which they do not fully understand. Step one in writing anything is to know what you’re writing about. Step two is to understand your audience. This doesn’t mean that when technical documentation is written it should include colloquialisms, vernacular, or regional phrases, but that it should be easily accessible and understood by consumers who are unfamiliar with the product.

Further strategic movement by industries is the idea of globalization. The true aim of a company is to make money; ok, understood. By reaching out to consumer territory they have not yet approached, companies and industries expand their potential growth market. Technical documentation must grow with business. Technical documentation has often been difficult for readers to relate to or get themselves engaged in – small wonder that technical documentation was loathed and strategically placed in the circular file. Today, technical documentation has the added hurdle of identifying with readers from different backgrounds, different languages, and different countries. Because technical documentation is meant to be instructional, it has to be extremely clear in meaning, and thorough in its explanations. It’s important to remember that consumers are usually only going to turn to technical documentation when they have a problem, or if the documentation is meant to be training material. Writers of technical documentation need to anticipate problems that will arise in the consumer’s daily use of a product. A great example to this issue occurred to me and my own family during the holiday season.

My mother is, as she terms it, “computer-illiterate.” Sometimes I’m lucky that she knows how to turn the computer on, much less navigate through the internet. Initially, I would get frustrated with her because she didn’t understand what I was trying to tell her. “Type the URL in the address bar” just didn’t cut it. First off, she had no idea what an “URL” was. So I had to explain, “URL is the web page address for where you want to go. It’s the identifier of the web page.” Then I gave her an example, www.shoap.com. “The address bar is at the top of your web browser, normally white, and shows the web address.” Ok. So now she knows how to get from one web page to another. Recently, she wanted to upload photos from her camera to Walgreens so that she could make copies of those photographs as Christmas presents. This was a difficult predicament, as I had to direct her how to do this over the phone. She was able to upload the photos from her camera to the computer on her own, but moving them from the computer to the website was causing problems.

In this instance I was removed from the consumer. I had to anticipate that she would not be as familiar as I was with uploading pictures and navigating through the website. Fortunately, I’ve used the upload procedure on the website before, so I was familiar with how it works, (step one complete!). Now I have to properly explain it to my mother, someone unfamiliar with the process (step two complete!), in a precise, easy-to-understand manner without oversimplifying: What I did for my mother was basically a walkthrough. I was on the phone with her, telling her what to do as I was also going through the process to make sure it was accurate. First, she had to open the web browser, (I advised her not to use Internet Explorer, but Mozilla Firefox, instead). She brings the browser up and I ask her to type in the address: www.walgreens.com into the address bar located at the top of the browser. We magically portal over to the website through the internet, and we are faced with the Walgreens’ home page. I ask her to click on the photo icon at the top of the page, which she does. She then has to log in; she already has a username and password, so she does that. Now we have a slight problem.

It appears that my mother’s web browser version is outdated and does not have the latest version of Flashplayer. My web browser is perfectly fine, so I have to walk her through updating Firefox. I search for “Adobe Flashplayer” in my search bar and come up with http://get.adobe.com/flashplayer/. I have to relay this to my mother, so I tell her to go to the address bar, delete the current address, and type the above mentioned URL. She does so, and it takes her to the installation page. I ask her to uncheck the McAfee Security Scan and click the yellow “agree and install now” button. I tell her to the save the file which pops up, and then the update downloads. I tell her to double-click on the install_flash_player.exe file, and the computer does its thing. But wait! We still have the Firefox program running! I ask her to close the browser by clicking the red X in the right hand corner, and then double-click the install file. The installation is successful; we close the dialogue box, and restart Firefox. We go back to walgreens.com, click the photo icon and she logs in again. Now I direct her to look for the “Get Started!” header in orange, and click on the “upload photos” text beneath it in blue. She does that and it brings up a pop-up for her to add to a new album or add to an existing album; she decides to add to a new album and names it. Then I ask her to click on the blue, “select photos” button on the bottom right. After that, she is taken to a folder to select photos. The folder is not the one she wants!

Now I have to walk her through changing the file path so that she can get to the folder which has the photos she wants to upload. I ask her if she sees the dialogue box that says, “Select file(s) to upload…” and she affirms. I tell her to go to the “look in:” area at the top of the box and click on the drop down menu. At this point, I’m not sure where she stored her photos, but I have a good idea: I tell her to click on the “My Documents” folder in the menu, and then click on the “My Pictures” folder in the box showing a lot of different folders. She then recognizes the title for her album, clicks on it, and sees the pictures she wants. Now I tell her to position her mouse in the white space above and slightly to the left of the first picture, hold the mouse, and move it to the bottom corner of the last picture she wants to select. I have to tell her this because Walgreens does not have a check mark option to select multiple photos, and it must be done in the drag-highlight method. After the photos are highlighted, I tell her to click the “Open” button, and the website automatically begins uploading each picture. Once all of the photos are marked “Done” the web page moves to a screen saying, “Your photos have been uploaded! What would you like to do next?” I tell her to click the “Order Prints” button, and follow the steps Walgreens provides from there.

The steps on the Walgreens photo uploading site are fairly good, especially since they anticipate the needs of consumers and alert them to things that will happen next, such as the “Order Prints” page. It reads, “Select the album with the photos you’d like to print. You’ll choose quantities and sizes on the next page. Need help?” And then directs consumers to click the photos they want to order, which conveniently show up in a side bar apart from the bulk of the album.

So how does this tie in to large-scale, profitable technical documentation for companies, and useful, instructional material for consumers? I’ve just demonstrated that while you should never patronize the consumer and oversimplify directions, you have to be aware of who your audience is when constructing and presenting technical documentation, training, or instructional material. This almost always means that you are going to have to explain methods in a simpler, yet thorough process.

My earliest recollection of instructional material came from second grade when we were asked to write instructions on how to make a peanut butter and jelly sandwich. I couldn’t believe my luck at the simplicity of the assignment! I initially wrote: put peanut butter on bread, put jelly on bread, and cover with second slice of bread. This was apparently wrong to my teacher. Why? Well, I had left a lot of things out. For example, where did I get the peanut butter and jelly? How did I get the peanut butter and jelly out of the jars? What did I use to put the peanut butter and jelly on the bread? “Well that’s stupid!” I said. “Everyone knows you have to open the jar, get a butter knife and put it in the jar to get the peanut butter and jelly, and then spread the peanut butter and jelly on the first slice of bread!”

Well, that’s probably true, people know how to make peanut butter and jelly sandwiches, and lots of things can be inferred, but when they are first taught, they have to be precise, step-by-step instructions, considering that the reader may never have done such a thing before. The peanut butter and jelly story is extreme, but if I had simply told my mother, “Go to walgreens.com, pick the photos you want and upload them, and then choose how many of what photo you want to order,” she wouldn’t have been any better off than when she first asked me for my help. In this way, technical documentation should be viewed as a communication meant to help others and educate them with precise, clear, and easily understandable instructions. I walked my mother through a – to her – complicated process, using precise instructions and minimal technical jargon. Any technical references I made, I explained in more familiar language. Overall, technical writers need to take into consideration who is reading the document, and what they are going to have questions about so that consumers can relate to their instructions and have a more enjoyable, and understandable experience with the product.

Tell Someone About This Post:

… we have come to value … working software over comprehensive documentation…

Agile Manifesto

We don’t do a lot of work with practitioners of agile methodologies. I think that’s partly because there’s some built-in hostility towards documentation in the values of agile development. Of course, while the Agile Manifesto is referring mostly to documentation for the front end of the cycle (i.e., the giant FRS), that hostility ends up spilling over to end-user documentation as well. (I don’t think that was the intention.)

Over the last couple of months, one of my main clients has been moving our documentation processes to an agile methodology in order to align with development processes.  It has been interesting, to say the least. The biggest change is the move towards small iterations of documentation that match the iterations of the development process. It means that instead of documenting twenty new features at the end of a three month development cycle, we document a handful of features (or parts of features) every couple of weeks.

What are the challenges?

Get me the code! One of the first challenges we faced was that there wasn’t yet a process in place to get the newest iterations of the applications to me as each iteration of development is completed. This one is a work in progress thus far, but getting the working software iterations to the doc team needs to become part of the process in order to do doc in an agile world.

Get in the conversation. The nice part about the giant FRS is that it’s (often? sometimes?) a great source of information for the end-user documentation. (We’ve converted specs to user manuals and user manuals back to specs, the latter not being a practice we would recommend.) Without the spec, you have a lot more work to figure out just what the application is doing and why. For this specific client, not much has had to change in this respect since I’ve already been able to spend a lot of time with the development honchos, been indoctrinated into their ticket tracker, and have a good background in their apps after several years working with them. Additionally, I’m now working with a great project manager who facilitates my information gathering needs.

Iterations don’t tell the whole story. Each of the iterations we’ve worked on so far has contained parts of features. The most challenging issue so far has been figuring out how to incorporate partially finished features into the overall story of the document as well as how to document the whole story of any given feature when only parts of the feature are complete. One strategy I’ve been using is taking a holistic look at each of the documents I’m working on before each iteration to identify areas that may be affected two or three iterations down the line in a sort of pre-emptive review.

Version control. Simply put, the more times you have to edit a document, the more version control can be an issue. Additionally, with the agile methodologies we have to worry about patching previous versions of the documentation while updates to the newest version are already in progress.

What are the benefits?

Eliminate the big push. The biggest benefit is eliminating the one huge documentation effort for each release. Iterations are quicker and more frequent, but the limited scope makes it easy to get a few changes done at a time.

More review cycles are always better. Of course, each iteration is supposed to come with its own review cycle. I’m willing to bet that some of those review cycles will be missed; however, even if only half of the iterations get a new review cycle, that’s still many more reviews for the documentation than you would get for that one big push.

On the same page. Agile documentation forces the documentation team to be on the same page as the development team. That makes it harder for this or that feature to slip past the documentation team. It also makes it easier for project management since you know just how far along the documentation effort is at any given time.

Get the doc team involved. Documentation folks have a natural affinity to other software related disciplines such QA and UX. How many times do technical writers say “Hey, that doesn’t work quite right” or “Hey, that’s really hard to use” when it’s too late to do anything about it? Getting the documentation folks involved in the development process while the software design is still an evolving thing can help to make the final product a more polished, usable application.

Tell Someone About This Post: