Writing Documentation & Training Materials Nikki Massaro Kauffman

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

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

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

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

Documentation Fundamentals Document every step/action.

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

Examples

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

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

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

Examples

Examples

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

Examples

Examples

Examples

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

Sample Style Guide Use bold, as in V. Keys

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

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

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

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

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

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

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

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

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

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

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

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

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.

Image Captures Capture images of icons that have no name.

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

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?

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

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

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

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

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

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

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

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

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

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

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

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.

Examples

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?

Examples

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.

Examples

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?

Examples

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?

Examples

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?”

Examples

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.

Questions?

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?