Effective Guides & Tutorials

1. Effective Guides & Tutorials

2. Your Documentation Project • Book proposal for a guidebook • One sample chapter • Word Range: 2400-3000 words

3. What is a manual? • Explains how to • Perform a task • Use a product • Master a technology • Types of manuals: • Cookbooks • Tutorials • Guides • References

4. Cookbook Style • Good for processes that must be completed in a certain order. • Bulleted list of ingredients/requirements • Numbered list of steps • Avoid cookbook style • if process can’t be easily broken into discrete steps. • if you want to provide more than simple instructions.

5. Tips for Cookbook Style • Is your list of ingredients/requirements complete? • Materials, equipment, skills, time? • Are your steps discrete? • No step should have multiple parts. • Did you define success? • How do you know if you did the step right? Wrong?

6. Tutorials • Takes reader gently through a series of steps to use a product or technology. • A helpful “lesson” rather than a numbered list of instructions. • Examples: • How to use Word to automatically generate a table of contents. • How to clean and maintain a rifle.

7. Tips for Tutorials • Give readers a taste of success ASAP. • Take little for granted. • Omit extraneous background info. • Move slowly, especially at beginning. • Identify confusing/dangerous aspects. • Test tutorials on beginners. • Introduce each topic one at a time.

8. How to Fly Fish • First, make a fly lure. • You must attach lure to fishing line. • Be careful not to injure yourself on hook. • Cast. • Enjoy a delicious fish dinner! • Tip: If you don’t catch any fish, you’re not doing something right. • If you do catch fish, congratulations!

9. Guides • Guidebooks are what readers turn to after reading tutorials to learn about more in-depth info and advanced topics. • Example: • Guide to Writing A+ Term Papers • Online Dating for Dummies

10. Tips for Guides • Empathize with readers. • What do they really want to learn? • Provide many relevant examples. • Balance simple with the occasional “real world” example. • Include figures, tables, images. • Provide background info when helpful. • Consider “chunking” material.

11. Part of Guide • The first step in becoming a successful deer hunter is to purchase a reliable and high quality rifle. There are many types of rifles, but here are the key factors to consider: • How much can I afford to spend? • With a little luck and patience, you can find a decent used hunting rifle for as little as $50. A high-quality, new rifle can cost as much as… • What caliber is best for deer hunting? • Blah blah..

12. What parts will you need? • Book Proposal • Annotated table of contents • Glossary • Index • Sample Chapter

13. Proposal Sections • Overview • Author Bio • Market • Competition

14. Overview • This guide is designed to introduce the wonderful world of hunting to beginners. We’ve written this guide with the complete novice in mind, someone who enjoys the outdoors, but has little to no hunting knowledge or experience. • Throughout this guide, we will discuss the following topics: • The goal of this guide is…

15. Author Bio • The author is Julie Smith, an avid gamer since she was old enough to plug a cartridge into an Atari 2600. • The authors are John Petriski, Ronald Warren, and Jill Laclure. John has spent the last two years touring the country’s best fishing spots…

16. Market • The target audience of this book is 25-45 year old males who spent a great deal of their youth playing videogames. • This book is intended for 25-45 year old single, widowed, or divorced women who are curious about online dating but unsure about how to proceed. Men of the same age bracket might also find it useful.

17. Competition • There have been two books in recent years that cover videogame history. The most popular is…However, our book… • Although there are currently no books specifically on this topic, there are several on closely related topics such as…

18. Glossary • A small dictionary that defines terms. • Keep definitions short. • Provide examples where helpful. • Limit terms to primary concepts. • Keep terms grammatically parallel. • Keep form of definition parallel. • Use alphabetical order.

19. Sample Terms • Buckshot: • A shotgun shell containing large shot, primarily used for hunting deer. Also see: Birdshot. • Game: • The types of animals pursued by hunters. Examples: Deer, squirrels, rabbits.

20. Table of Contents • Think of first-level headers within each chapter as forming a list. • Keep headers grammatically parallel and consistent. • Ensure header names contain key terms. • Keep chapter and header names concise. • In a large manual, organize chapters into sections.

21. Sample TOC • Preparing for your first hunt. • Selecting the right attire. • Selecting the right firearm and ammunition. • Setting up your stand… • Waiting for prey. • Watching, listening, and staying alert… • Field dressing your deer…

22. Annotated TOC • Chapter two will cover setting up an online profile on several of the major dating sites. Tips will be provided for taking a good photo, describing one’s hobbies…

23. Index • Time consuming, but worth it. • Questions to ask: • What would I look up in the index? • What would reader look up?

24. Index tips • Create precise entries; avoid vagueness • Avoid misleading entries. • Permute index entries. • Provide index entries for related concepts, not just words on page. • Keep everything grammatically consistent. • Index info included in graphs and tables. • Index should be 5-7% the length of document.

25. Index Examples • Too general: • Chapter • Processes • Better: • Field dressing • Guns, see Rifles. • Permutations and Second Level: • Field dressing • Deer…. • Squirrels ….

26. Summing Up • Does preface identify audience and purpose? • Do TOC and index list every keyword or concept reader might need? • Do opening sections introduce topic? Do concluding sections summarize it? • Nice mix of text, tables, graphics? • Are sections organized logically?