1. Writing Documentation & Training Materials
Nikki Massaro Kauffman

2. Overview Documentation Fundamentals Sample Style Guide Image Captures
Feedback & Data Collection

3. Overview Documentation Fundamentals Sample Style Guide Image Captures
Feedback & Data Collection

4. Documentation Fundamentals
Document steps/actions in order. 3 2 1

5. Examples Click Print… under the File menu. -OR-
Under the File menu, click Print…

6. Documentation Fundamentals
Document every step/action.

7. Documentation Fundamentals
Answer the following with each step:
Where am I?
What should I do?
What will happen? ? ? ?

8. Examples

9. Documentation Fundamentals
Keep the steps short and simple. Use right arrows (→).

10. Examples Which version facilitates scanning?
On the Format menu, select Alignment and click Left.
Click Format, Alignment, Left.
Click FormatAlignmentLeft.

11. Documentation Fundamentals
Use the language that the application uses for its menus, tools, etc., but avoid jargon.
Jargon Monoxide

12. Examples

13. Examples

14. Documentation Fundamentals
Don’t assume your audience is reading sequentially from beginning to end. 3 2 1

15. Examples

16. Examples

17. Examples

18. Overview Documentation Fundamentals Sample Style Guide Image Captures
Feedback & Data Collection

19. Sample Style Guide
Use bold, as in V.
Keys

20. Keys Sample Style Guide
Abbreviate with all capital letters and no period, as in CTRL or ALT.
Keys

21. Keys Sample Style Guide
Use a plus sign (+) for keys held together, as in CTRL+ALT+DEL or CTRL+V.
Keys

22. Sample Style Guide User Input
Any item user can select (tabs, buttons, links, etc.) should appear in bold.
User Input

23. Sample Style Guide User Input
Any text a user must type should be in a fixed-width font.
User Input

24. Sample Style Guide User Input
Any text that varies based on the user's personal situation should be italicized, as in "abc123" for "userid".
Do not use real users in your examples.
User Input

25. Misc. Sample Style Guide
New terms can appear in bold font the first time they are used.
Misc.

26. Misc. Sample Style Guide
Right arrows(→) can be used as shorthand for a specific path, as in “File→Print...”
Misc.

27. Misc. Sample Style Guide
Use your guidelines and templates as a style guide for consistency.
Misc.

28. Overview Documentation Fundamentals Sample Style Guide Image Captures
Feedback & Data Collection

29. Image Captures
Capture key steps, but don't overdo it.

30. Image Captures
In introductory sections, you may choose to capture dashboards.

31. Image Captures
Capture dialogs and windows that require key decisions and/or user input.

32. Image Captures
Capture the screen If the words alone fail to describe what the user should see or do.
Edit the capture (crop, draw arrows, etc.) to call attention to what you are illustrating.

33. Image Captures
Capture images of icons that have no name.

34. Overview Documentation Fundamentals Sample Style Guide Image Captures
Feedback & Data Collection

35. Feedback & Data Collection
For Group Discussion…
From your perspective, what do you need to make you documentation efforts successful?
What do your users need to be successful?

36. Feedback & Data Collection
Document
Review
Helpdesk
Web Analytics
The
Documentation
Process

37. Feedback & Data Collection
Reviewing Your Work:
Find a peer as a proofreader.

38. Feedback & Data Collection
Reviewing Your Work:
Find a technical expert to review for accuracy.

39. Feedback & Data Collection
Reviewing Your Work:
Find a user or two to review for simplicity.

40. Feedback & Data Collection
For HelpDesk Requests… Search for a documented answer.

41. Feedback & Data Collection
For HelpDesk Requests… If it’s out there, send link to documentation & explanation of how to find it by searching.

42. Feedback & Data Collection
For HelpDesk Requests… If it’s not, document it first, and then send link.

43. Feedback & Data Collection
Teaching Them to Fish… It develops and maintains knowledge base documentation.
Photo Credit: Fishing Harbour in Setubal by fotografar

44. Feedback & Data Collection
Teaching Them to Fish… It ensures a consistent party-line answer.
Photo Credit: Fishing Harbour in Setubal by fotografar

45. Feedback & Data Collection
Teaching Them to Fish… It saves helpdesk staff the redundant effort of providing an answer if one is already out there.
Photo Credit: Fishing Harbour in Setubal by fotografar

46. Feedback & Data Collection
Teaching Them to Fish… It’s a subtle way to show user how to search for answers within the knowledge base.
Photo Credit: Fishing Harbour in Setubal by fotografar

47. Feedback & Data Collection
Using Web Analytics Data:
Visitors & Pageviews are only noteworthy when you look at trends over time.
New ANGEL version, new semester, new marketing, etc.

48. Examples

49. Feedback & Data Collection
Using Web Analytics Data:
Top Content/Content by Title will show you the topics being accessed the most.
Are these topics for more targeted training?

50. Examples

51. Feedback & Data Collection
Using Web Analytics Data:
Users don’t just access a site from the home page. Top Landing Pages will show which pages are being used to access your knowledge base.
New ANGEL version, new semester, new marketing, etc.

52. Examples

53. Feedback & Data Collection
Using Web Analytics Data:
Check the Referring Sites to see who is sending visitors to your documentation and/or to evaluate how well you have marketed them.
Are your referrals from other websites, FB, twitter, etc. working?

54. Examples

55. Feedback & Data Collection
Using Web Analytics Data:
Check the Keywords to see what language your visitors use to search for documentation.
Do you need to revise you documentation to include some of these keywords your visitors are using?

56. Examples

57. Feedback & Data Collection
Using Web Analytics Data:
You can create Advanced Segments to filter for specific questions like “What content do people with specific browsers or access?”

58. Examples

59. Feedback & Data Collection
Using Web Analytics Data:
Remember that Web Analytics gives you quantitative data. Follow-up with HelpDesk calls, user comments, and focus groups for detailed qualitative data.

60. Questions?

61. Final Thoughts
As a group, what will you need to make your documentation successful? As individuals?
How can you create documentation from the user’s perspective instead of your own?
How can you make documentation easy to find?
From where you sit, what information can you pass on to others in order to improve the documentation process?