Developing Workflow-Based Help

Editor's Notes

1. Hello, everyone! Welcome to “Developing Workflow-Based Help”
2. This TOC is from my very first help project, which was called the Arrow Online Help . . . This help project was organized by the menus in the application, just like its accompanying user guide.
3. The TOC of another of my help projects resembled this TOC: Introduction, User Interface, Tasks, Reference, and Support books. Each book contained several topics. Not displayed here, but the Tasks book can contain sub-books that break the software tasks down by type of job. In the example above, the Tasks books could contain sub-books for delivery tickets, invoices, repair tickets, and reporting books. Also, Analysis, Interpretation, and Reporting could be books.
4. My last classic example is a project I did at BMC Software. The organization of this help project was consistent with all of the other knowledge modules in the Performance Managers software. This help project was organized by application class, parameters, and tasks. Earlier help projects for PATROL (the Performance Manager predecessor) also contained a book for menu commands. This help project organization allowed the help projects for each of the knowledge modules to merge together correctly during installation. In all three of these examples, the thing that is missing is learning how the customer really uses the software.
5. We followed our templates, right? So how about a better template?
6. I watched our SME work in our software, and I drew workflow diagrams. Workflow diagrams, which are a graphical way to show your user how to do their work in your application, included not only shapes for how to use our software, but shapes that show the users how their training and knowledge cause them to analyze data and make decisions with the software.
7. First, let’s talk about the TOC: If you are creating a new help project, use this organization right from the start. If you have an existing help project, do some rearranging. As you create the TOC, you can create your workflow topic files. Later go back and write an introduction (home page for the help) that highlights the workflow topics.
8. Watch someone working, whether it is your SME or a real-life user. When you try to diagram a workflow without observing, tasks and processes tend to get forgotten. Has anyone ever done user task analysis with post-it notes? Yeah. You use post-it notes so you can add the tasks and processes you forget. You can start by drawing the flowchart you think the user follows, but then do some actual observation and make sure you recorded everything.
9. For example, this is a workflow for creating a help project: Your workflow tasks could include: Creating a new help project with a wizard Adding a table of contents Your processes could include: observing users drawing flowcharts Planning the TOC for your help project
10. This is another workflow for working in a help project: This workflow includes: Copying information from the tool that holds your Agile development stories Creating topics Opening topics Editing HTML tags or applying styles in your help topics Editing content Editing topic properties, including index entries
11. Flowchart software: Visio Help Authoring Tool: RoboHelp
12. Here are some of the common shapes for a flowchart. I use the shapes in the following way: Terminator marks the start and stop of the workflowUsually, these say “Start” and “Stop” Process shape is an activity that the user performs; the activity does not use the software you are documentingFor example: observing users; analyzing the data displayed on the screen; checking the help in to a source control tool. Task shape is an activity that the user performs with the software; these shapes are linked to task help topicsFor example, creating a help project, adding a topic to the help project; adding index entries to a help topic Decision Diamond asks a question, and the answers lead to different workflows: Have you added all of the topics to the project? Yes? Create a TOC. No? Add missing topics. Did you add index entries to the topic? No? Add index entries. Yes, review the index for accuracy. Usually the answer to a decision diamond is yes or no. Switch out to Visio to show creating the flowchart and saving it as a png file.
13. Going back to the flowchart example on slide 13, say your daily work involves creating a help project. 1 - Your introduction should address why you want to create a new help project and what all information should be included in your help project. 2 – Workflow graphic for creating a new help project 3 - Information the user needs before they begin: name of the software to be documented; several workflows 4 – Screen shot of the result of completing the workflow 5 -Links to the previous and next workflows, if you have them 6 - Section, with the heading Workflow Links, with links to your task topics; these links match the links on your workflow diagram. Including this second set of links lets your users get to the information multiple ways. 6 - Links to related topics, at your discretion
14. Let’s talk about browse sequences and breadcrumbs: As the users go through your workflow-based help, wouldn’t it be great if there was a linear way for them to move easily to the next help topic in the flow? Yes, it would, so you should create a browse sequence (however you do that in your help authoring tool). In my project, I was not able to use a browse sequence because one of the topics was in multiple workflows, so I create breadcrumbs at the top of my workflow task topics.
15. For example, creating a help project leads to updating the help project that leads to retiring the help project. You can create an overview workflow topic with a flowchart of all three workflows fitting together. The overview topic can include the introduction and other elements from the template if you want. The overview is optional. If you include one, put it at the book level for your Workflows book.
16. This is the top part of the generated help topic. It includes: Breadcrumbs at the top Introduction and goal Description of the flowchart and actions you can perform Flowchart Information you need to begin creating the help project Screen shot of the expected result (in this case a screen shot of RoboHelp) Link to the next workflow topic (if any other workflow topics exist); you would also include a link to the previous workflow Links to each of the task topics; these links are also included on the flowchart itself This topic screenshot does not contain links to related topics Switch out to RoboHelp if time