| |
| |
| Our Contract with You, the Reader | |
| |
| |
| List of Chapters | |
| |
| |
| Dedication | |
| |
| |
| Acknowledgments | |
| |
| |
| About the Authors | |
| |
| |
| How to Download the Files | |
| |
| |
| Introduction | |
| |
| |
| |
| Planning an Online Help Project | |
| |
| |
| Why plan an online help project? | |
| |
| |
| What process is used in an ideal help project? | |
| |
| |
| |
| Analyze the audience, plan the project, and write the plan | |
| |
| |
| |
| Develop high-level specifications | |
| |
| |
| |
| Develop detailed specifications | |
| |
| |
| |
| Perform a detailed task analysis | |
| |
| |
| |
| Build and evaluate a prototype help system | |
| |
| |
| |
| Develop an outline and map of the help project | |
| |
| |
| |
| Write, index, and edit the help topics | |
| |
| |
| |
| Review the help topics | |
| |
| |
| |
| Test the help | |
| |
| |
| |
| Release the help with the product | |
| |
| |
| |
| Evaluate the help and plan for improvements | |
| |
| |
| What are the roles in an online help project? | |
| |
| |
| Project manager/planner/producer's role | |
| |
| |
| Writer's role | |
| |
| |
| Editor's role | |
| |
| |
| Graphic artist's or illustrator's role | |
| |
| |
| Instructional designer's role | |
| |
| |
| Programmer's role | |
| |
| |
| Multimedia producer's role | |
| |
| |
| Indexer's role | |
| |
| |
| Localization and translation coordinator's role | |
| |
| |
| Usability tester's role | |
| |
| |
| Quality assurance (QA) person's role | |
| |
| |
| How much time is required for producing online help? | |
| |
| |
| Overall time required | |
| |
| |
| Time required for different activities | |
| |
| |
| Number of help topics required | |
| |
| |
| Who does what, when? | |
| |
| |
| Organizing the flow of writing, editing, reviewing, and testing | |
| |
| |
| Stages of help and software development | |
| |
| |
| How many reviews are needed, and when? | |
| |
| |
| What types of testing are required? | |
| |
| |
| Methods for editing and reviewing | |
| |
| |
| Choosing help-development tools | |
| |
| |
| Conclusion | |
| |
| |
| |
| Analyzing Audiences and Tasks | |
| |
| |
| Who are the audiences? | |
| |
| |
| |
| Audience analysis for TreeLine | |
| |
| |
| |
| Audience analysis for a multi-user database program | |
| |
| |
| Working with user profiles and personas | |
| |
| |
| |
| Personas for TreeLine | |
| |
| |
| What are the audiences' tasks? | |
| |
| |
| |
| User task analysis for TreeLine | |
| |
| |
| |
| User/task matrix for a multi-user database program | |
| |
| |
| |
| Task map for TreeLine | |
| |
| |
| Flow diagram | |
| |
| |
| Working with use cases and user scenarios | |
| |
| |
| |
| Use case and user scenario for an e-mail program | |
| |
| |
| What questions will the audience ask? | |
| |
| |
| Build lists of users' questions and help topic types | |
| |
| |
| |
| Part of a task-topic list for TreeLine | |
| |
| |
| Conclusion | |
| |
| |
| |
| Developing Specifications | |
| |
| |
| High-level specifications | |
| |
| |
| How will the online help coordinate with other user documents? | |
| |
| |
| What type of help will best fit the application? | |
| |
| |
| How will the help be connected to the application? | |
| |
| |
| What media types are required? | |
| |
| |
| What tools are needed? | |
| |
| |
| What information types and levels are required? | |
| |
| |
| What topic types are required? | |
| |
| |
| How will the help windows (or pages) be presented? | |
| |
| |
| What navigation aids will be used? | |
| |
| |
| How will the help meet localization criteria? | |
| |
| |
| How will the help meet accessibility criteria? | |
| |
| |
| Detailed specifications | |
| |
| |
| Related documents (primary sources) | |
| |
| |
| Writing conventions | |
| |
| |
| Terminology | |
| |
| |
| Design and layout | |
| |
| |
| Help navigation scheme | |
| |
| |
| Content of topic types | |
| |
| |
| Project-specific style guide | |
| |
| |
| Conclusion | |
| |
| |
| |
| Prototyping the Help System | |
| |
| |
| Why build a prototype of a help system? | |
| |
| |
| Building a high-level concept and design prototype | |
| |
| |
| What to include in a high-level prototype | |
| |
| |
| Create a working high-level prototype | |
| |
| |
| Building a detailed contents prototype | |
| |
| |
| Outline and map the help project | |
| |
| |
| Use the outline and roadmap to build a detailed prototype | |
| |
| |
| Fill in the details | |
| |
| |
| Conclusion | |
| |
| |
| |
| Avoiding Common Problems | |
| |
| |
| |
| I can't find what I'm looking for | |
| |
| |
| |
| I can't figure out what's going on | |
| |
| |
| |
| I can't figure out what will happen when I do something | |
| |
| |
| |
| There's too much detail | |
| |
| |
| |
| There's not enough detail | |
| |
| |
| |
| I can't get to the help when I want it | |
| |
| |
| |
| The program isn't working the way the help says it should | |
| |
| |
| |
| Help says what the system does, but not how to use it | |
| |
| |
| |
| I want a bigger picture of what this program can do | |
| |
| |
| |
| The help is inconsistent and badly written and formatted | |
| |
| |
| Categorizing problem severity | |
| |
| |
| Conclusion | |
| |
| |
| |
| Producing the Table of Contents and Index | |
| |
| |
| Terminology | |
| |
| |
| Designing a useful table of contents | |
| |
| |
| Structure | |
| |
| |
| Presentation | |
| |
| |
| Reviewing a table of contents | |
| |
| |
| |
| Table of contents with subtle problems | |
| |
| |
| |
| A more user-friendly table of contents | |
| |
| |
| |
| Another user-friendly table of contents | |
| |
| |
| |
| A different approach: table of contents for a Web site | |
| |
| |
| Designing a useful index | |
| |
| |
| Reviewing an index | |
| |
| |
| |
| An index with problems | |
| |
| |
| |
| A better index for an e-mail program | |
| |
| |
| |
| An index with clearly differentiated entries | |
| |
| |
| |
| An automatically generated index for a Web site | |
| |
| |
| |
| A bad example: combining index and search | |
| |
| |
| Conclusion | |
| |
| |
| |
| Providing Navigation and Context | |
| |
| |
| Avoiding problems | |
| |
| |
| Using cross-references and other links | |
| |
| |
| Reviewing cross-references and other links | |
| |
| |
| Using expanding sections | |
| |
| |
| Providing for reader-defined navigation | |
| |
| |
| Navigation pane | |
| |
| |
| Bookmarks and Favorites | |
| |
| |
| History list (Web browsers) | |
| |
| |
| Using visual aids such as icons or color | |
| |
| |
| Reviewing visual aids | |
| |
| |
| Using browse sequences | |
| |
| |
| Reviewing browse sequences | |
| |
| |
| Providing context information in the text | |
| |
| |
| Using breadcrumbs: showing the path to a topic | |
| |
| |
| Using words to provide context | |
| |
| |
| Telling users what to expect | |
| |
| |
| Reviewing context information | |
| |
| |
| Conclusion | |
| |
| |
| |
| Meeting the Needs of Novices to Experts | |
| |
| |
| Designing help to meet a range of users' needs | |
| |
| |
| Consider different user types | |
| |
| |
| Define different information types | |
| |
| |
| Choosing delivery methods | |
| |
| |
| Embedded help | |
| |
| |
| Assistance for novice users | |
| |
| |
| Providing for users' preferences | |
| |
| |
| Integrating the help system with other documents and systems | |
| |
| |
| Avoiding common problems | |
| |
| |
| Not enough detail | |
| |
| |
| Too much detail | |
| |
| |
| Conclusion | |
| |
| |
| |
| Linking from Application to Help | |
| |
| |
| Providing context-sensitive help | |
| |
| |
| Using topic IDs and context numbers | |
| |
| |
| Solving context-sensitive help complications | |
| |
| |
| Providing help for dynamic (variable) dialogs | |
| |
| |
| Providing help for dialogs with multiple tabs | |
| |
| |
| Providing field-level help within dialog-level help | |
| |
| |
| Providing context-sensitive help for Web pages | |
| |
| |
| Identifying common linking problems | |
| |
| |
| Conclusion | |
| |
| |
| |
| Copyediting and Production Editing | |
| |
| |
| Defining editorial roles | |
| |
| |
| Substantive editing of online help | |
| |
| |
| Copyediting online help | |
| |
| |
| Example of accurate content requiring rewording | |
| |
| |
| Using a style guide | |
| |
| |
| What belongs in a style guide? | |
| |
| |
| Company and project style guides | |
| |
| |
| Production editing online help | |
| |
| |
| Finding and fixing display problems | |
| |
| |
| Finding and fixing accessibility problems | |
| |
| |
| Prioritizing changes | |
| |
| |
| Conclusion | |
| |
| |
| |
| Usability Testing on a Budget | |
| |
| |
| What is usability? | |
| |
| |
| Planning for usability testing | |
| |
| |
| What to test when | |
| |
| |
| Usability testing during planning stage | |
| |
| |
| Usability testing during prototyping stage | |
| |
| |
| Usability testing during early draft stage | |
| |
| |
| Usability testing during production editing stage | |
| |
| |
| Conducting usability tests | |
| |
| |
| Defining testing objectives and methods | |
| |
| |
| Writing test materials (scenarios for testers to follow) | |
| |
| |
| Recruiting test subjects | |
| |
| |
| Setting up the test environment | |
| |
| |
| Conducting the test | |
| |
| |
| Analyzing and reporting on the results | |
| |
| |
| Prioritizing problems and making changes | |
| |
| |
| Conclusion | |
| |
| |
| |
| Sample Plans and Specifications | |
| |
| |
| Templates | |
| |
| |
| |
| Online help plan for TreeLine | |
| |
| |
| Purpose of project and product | |
| |
| |
| Audience | |
| |
| |
| Competitors, previous software, or integrated systems | |
| |
| |
| Help development process | |
| |
| |
| Assumptions, dependencies, risks | |
| |
| |
| Schedule | |
| |
| |
| Contingency plans | |
| |
| |
| Related documents | |
| |
| |
| |
| High-level specifications for TreeLine help | |
| |
| |
| Related user documentation | |
| |
| |
| Type of help to be provided | |
| |
| |
| Interactions between help and application | |
| |
| |
| Media types to be used | |
| |
| |
| Tools for writing, editing, indexing | |
| |
| |
| Topic types required | |
| |
| |
| Presentation of help windows | |
| |
| |
| Navigation aids | |
| |
| |
| Accessibility criteria | |
| |
| |
| |
| Detailed specifications for TreeLine help | |
| |
| |
| Primary sources | |
| |
| |
| Writing conventions | |
| |
| |
| Terminology | |
| |
| |
| Abbreviations and acronyms | |
| |
| |
| Design and layout | |
| |
| |
| Content of topic types | |
| |
| |
| Conclusion | |
| |
| |
| |
| Help Types and Tools | |
| |
| |
| Types of help | |
| |
| |
| On Windows systems | |
| |
| |
| On multiple platforms using a Web browser | |
| |
| |
| On Apple Macintosh systems | |
| |
| |
| On Linux systems | |
| |
| |
| Tools | |
| |
| |
| Help-authoring tools running on Windows | |
| |
| |
| Other tools running on Windows | |
| |
| |
| Tools running on Macintosh operating systems | |
| |
| |
| Linux | |
| |
| |
| |
| For More Information | |
| |
| |
| General references | |
| |
| |
| Accessibility | |
| |
| |
| Audience analysis and personas | |
| |
| |
| Graphics | |
| |
| |
| Help types and tools | |
| |
| |
| Indexing | |
| |
| |
| Planning and specifications | |
| |
| |
| Usability | |
| |
| |
| Writing, style, and copyediting | |
| |
| |
| |
| Glossary | |
| |
| |
| |
| Checklists | |
| |
| |
| Planning the help project | |
| |
| |
| Analyzing audiences and tasks | |
| |
| |
| Developing specifications | |
| |
| |
| Developing a prototype | |
| |
| |
| Developing the table of contents | |
| |
| |
| Developing the index | |
| |
| |
| Reviewing the help system as a whole | |
| |
| |
| Reviewing embedded help | |
| |
| |
| Reviewing the contents of help topics | |
| |
| |
| Copyediting | |
| |
| |
| Production editing | |
| |
| |
| Usability testing | |
| |
| |
| Index | |