Developing Workflow-Based Help
•Transferir como PPTX, PDF•
0 gostou•42 visualizações
Often, our online help is organized by user interface elements, menu commands, tasks, and reference information. In this presentation, we will look at a different way of organizing the information by workflow. The finished help includes not only the classic elements, but also shows the user how they will put the software or hardware to work in the field.
Recomendados
Recomendados
Mais conteúdo relacionado
Semelhante a Developing Workflow-Based Help
Semelhante a Developing Workflow-Based Help (20)
Mais de Cindy Pao
Mais de Cindy Pao (20)
Último
Último (20)
Developing Workflow-Based Help
- 2. During this session we will Talk about how we organize online help: See the TOCs for some classic help projects Propose a new TOC for help projects, including a new type of topic Discuss how to develop workflows for a help project Incorporate the workflows into a help project
- 3. About Cindy Pao Senior technical writer, currently develop online help and release notes for oilfield software Associate Fellow of STC STC involvement includes, but is not limited to, Director-at-Large on the STC Board; Chair, vice chair, and member of multiple STC committees; President, Co-Manager, and member of several communities Conference, program meeting, workshop, and webinar presentations include “New Leader Table: The Basics of Running a Community” at the 2017 Leadership Program, “Using a Customer Response System in Writing and Updating User Documentation” at the 2006 STC conference, and “Creating a WinHelp Project” workshop in 2001.
- 5. Disclaimer The help system on which I developed workflow-based help is for proprietary software. The workflow-based help system you will see in this presentation has been created for this presentation.
- 6. Goals This presentation is about getting to know our customers. We need to find out how they work so that we can design documentation to help our customers get their jobs done. Workflow-based help is one way…
- 7. Classic Online Help Structures
- 8. Classic Online Help Structures
- 9. Classic Online Help Structures
- 10. What did we do before? We added as many topics as we could We organized all of these topics into books We put conceptual topics at the beginning of the TOC With that much information, if your application didn’t have context-sensitive help, we probably made it difficult for our users to find information
- 11. Let’s do something better Work with a user or SME and find out how your users really use the software
- 12. Do this in your help authoring tool Re-Organize your help project TOC: Put the workflow help topics at the beginning of the TOC Put user interface topics at the end of the TOC Put task topics in the middle of the TOC, and work with your user or SME to group those topics logically into sub-books, if necessary Create workflow help topics Give your workflow help topics the spotlight by including links in the home page for your help
- 13. Start Your Project Work with your user or SME to identify what goal your user needs to accomplish: I need to create a new help project I need to configure a development project I need to receive documents into a file I need to rent tools to a customer For each of the goals: Identify each of the activities involved, whether the user is using the software (tasks) or using the brain (process) Create a flowchart
- 16. Next . . . Create the flowcharts in flowchart software (like Visio) Save each flowchart as a graphics file (*.png works fine) Create workflow help topics (using a HAT)
- 18. Workflow Help Topics Introduction with one of your user’s goals Workflow graphic with hotspots Information the user needs before they begin Result of completing the workflow Links to the previous and next workflow help topics Alternate links to the workflow task topics Links to any related topics
- 19. Finish the Workflow Topics Add the workflow topics to the TOC in their own book Create index entries for your workflow topics Add glossary terms Create a browse sequence or add breadcrumbs
- 20. Overview Workflow Topics When you finish your individual workflow topics, try to create an overview workflow topic Ask your user or SME how the individual workflow topics fit together
- 22. What we covered today Advocating for your customer by Re-organizing the online help TOC Developing workflow diagrams Incorporating the workflow diagrams into your help project
- 23. What questions do you have for me?
- 24. Contact Information Email: cindy@paofamily.com Twitter: @cindypao Linked In: Cindy Pao Facebook: Cindy Klaesges Pao
Notas do Editor
- Hello, everyone! Welcome to “Developing Workflow-Based Help”
- 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.
- 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.
- 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.
- We followed our templates, right? So how about a better template?
- 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.
- 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.
- 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.
- 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
- 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
- Flowchart software: Visio Help Authoring Tool: RoboHelp
- 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 workflow Usually, these say “Start” and “Stop” Process shape is an activity that the user performs; the activity does not use the software you are documenting For 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 topics For 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.
- 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
- 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.
- 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.
- 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