1. YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK Kate Schneider Senior Technical Writer, MadCap Software @KATESCHNEIDER | #STC16

2. ABOUT KATE MadCap Software Senior Technical Writer 9 years in software industry  6 as a technical writer  3 as a proposal writer Interests  Single-sourcing, instructional design, translation  Video games, craft beer, dogs @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

4. WHAT WILL YOU LEARN? Why do you need a Documentation Handbook? What is (and isn’t) a Documentation Handbook? How to create it How to maintain it How to train with it Best practices @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

5. THE PROBLEM No instruction from previous writer Inadequate time for 1-on-1 training Outdated training manuals Conflicting information Thrown in the deep end @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

6. THE SOLUTION: THE DOC HANDBOOK Central repository kept in authoring tool Review, update, and add  Information stays current Reference and training tool Establish consistent voice and workflow Combats knowledge loss, inadequate time, redundant materials @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

7. WHAT A DOCUMENTATION HANDBOOK IS How your team writes its documentation. Training  Procedures  Voice  Authoring tool Reference  Internal procedures/how-to  Style guides Sandbox @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

8. WHAT A DOCUMENTATION HANDBOOK IS NOT Your actual Help project Copy of a published style guide (e.g., Chicago) Authoring tool Help @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

9. CREATING THE DOC HANDBOOK Set it up like your main Help project  Import conditions, styles, page layouts, reusable content  Bind to source control  Authoring tool agnostic Most important info and procedures Info you’d want to know on your first day  Welcome  How-To  Style Guides @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

10. WELCOME TOPIC Info about basic or important job tasks Reminders or guidelines Links to Read First topics @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

11. Styled using Flare Help stylesheet Read this stuff first! Other important tasks Team guidelines @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

12. HOW-TO TOPICS Department procedures and workflows How does your team use:  Authoring tool features  Your company’s software  Third-party tools Login information, websites, etc. @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

13. Does not rewrite Flare Help Gives information about how our team uses snippets @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

14. EXAMPLE: HOW-TO TOPIC Topics look just like topics in Flare’s help: conditions, drop-downs, styles, etc. @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

15. STYLE GUIDES Internal/department style information  Capitalization  Product names  Hex/RGB colors  Deviations from your main style guide Terms you’re always looking up? Add them! Link to company/published style guides @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

16. How our team uses punctuation Noting a common error @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

17. AUDIENCE PARTICIPATION! @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

18. MAINTAINING THE DOC HANDBOOK Most maintenance is done by new writers… Keep it current Add info as necessary  Especially true for lone writers!  Schedule time if necessary “To Do” topic, annotations @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

19. TRAINING WITH THE DOC HANDBOOK When most content is added Learning workflows and procedures Four stages  Reading  Updating  Writing  Review @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

20. READING Learn procedures Ask questions! Independent learning @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

21. UPDATING Learn voice, style Out-of-date, errors? What can you add?  Notes?  Screenshots?  Reusable content? @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

22. WRITING Practice techniques & workflows Add new topics, rewrite topics that need it “To Do” topic @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

23. REVIEW Typical internal review methods  Alternative methods? Review content, voice/tone, grammar  Track changes Peer reviews, team leader  Meet and discuss changes, questions, etc. Update Doc Handbook if necessary @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

24. AUDIENCE PARTICIPATION! @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

25. DOC HANDBOOK BEST PRACTICES DO… Work exclusively in the DH Make the full Help project available Collaborate with other team members Let new writers ask questions and make suggestions @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

26. DOC HANDBOOK BEST PRACTICES DON’T… Neglect the DH! Try to document everything on Day One Rewrite existing documentation @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

27. THANKS! KEEP IN TOUCH! @MadCapSoftware @MadCapDocTeam @kateschneider @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK

28. QUESTIONS? @KATESCHNEIDER | #STC16 | YOUR SECRET WEAPON: THE DOCUMENTATION HANDBOOK