is your documentation relevant for the 21st century · pdf file · 2016-04-30is...

ERICSA 53rd Annual Training Conference & Exposition ▪ May 1 - 5 ▪ Myrtle Beach, South Carolina

IS YOUR DOCUMENTATION RELEVANT FOR THE

21st CENTURY?

Cindy Holdren, Center for the Support of Families Michelle Le Feve, Courtland Consulting

Marcia Witt, Courtland Consulting


If you don't care about your product, why should I?: Writing Effective Training & Technical Documentation

Quality training materials and user documentation decreases the likelihood that users have issues with your product or service and it reduces the need for help

desk support. The key to writing successful documentation is in the style and format of the document. No matter how good the information is, if it is not written in clear

language and cleanly presented it can be difficult to use. Documentation should be easy to read, easy for the reader to understand and well organized. Writing effective documentation is time consuming, but creating documentation that is consistent in tone and language and professionally styled will increase your credibility, provide a more engaging user experience and reduce overall support costs. This session will

cover steps for producing quality documentation and present practical tips and tricks to increase your writing efficiency through the use of style guides and templates.

Participants will be provided with samples as a take away.

Is Your Documentation Relevant for the 21st Century?

With 191 million US consumers using smartphones, is your documentation evolving to meet the needs for the millennial generation? Creating policy, training or technical materials that are consistent in tone, language and professionally styled increases your credibility, provides a more engaging user experience, and reduces overall support costs. This session provides best practices and resources to increase your writing efficiency and usability for the 21st Century.


Cre

atin

g B

right

er D

ays

for F

amili

es

Great Documentation

Customer Satisfaction =


Cre

atin

g B

right

er D

ays

for F

amili

es

Keys to Relevant Documentation

The Writing Process

Design, Organization & Management

Trends & Tools

4


Cre

atin

g B

right

er D

ays

for F

amili

es

The Writing Process

5


Cre

atin

g B

right

er D

ays

for F

amili

es

Key Points The writing process presents the steps

from prewriting through the finished product

There are several unique considerations when creating web documentation

6

The Writing Process The Writing Process

7

Prewriting Editing

Collaborating

Drafting

Publishing

Revising


Cre

atin

g B

right

er D

ays

for F

amili

es

Prewriting Think about the audience

What do they need to know? Review other documents Choose a structure

More important for larger documents Different for web content

Generate ideas Brainstorm Talk with colleagues

8


Cre

atin

g B

right

er D

ays

for F

amili

es

Drafting Just start writing

Don’t worry about spelling, sequencing

Put down what you know and what you think about the topic Add notes where you may be missing

information Keep audience in mind

What do they need to know?

9


Cre

atin

g B

right

er D

ays

for F

amili

es

Revising & Collaborating Revise

Add Rearrange Replace Remove Start at the top and do repeatedly Take a break and go back when fresh

Collaborate Formal Informal

10


Cre

atin

g B

right

er D

ays

for F

amili

es

Editing & Publishing Edit

Slice and dice Check for logic Check for errors and omissions Repeat above steps numerous times!

Publish Final destination Website Report Other document

11

12

Average page visit is less than 1 minute

Source: http://www.digitalgov.gov/2014/04/04/heatmapping-tools-show-whats-hot-on-your-pages/

Scanning the Web


Cre

atin

g B

right

er D

ays

for F

amili

es

Scanning the Web

Viewers scan but do not read Scan is from left to right mostly at the

top of the page Viewers read headings, not dense text

Bite, snack, meal approach Bite – 10 words or less; think heading Snack – summary in 1 sentence Meal – full content

13

Example – Bite, Snack, Meal

Bite, Snack, Meal 14


Cre

atin

g B

right

er D

ays

for F

amili

es

Writing Web Content

Organize content using the inverted pyramid principle to prioritize text

to

Conclusions and takeaways

Supporting details

Background

15


Cre

atin

g B

right

er D

ays

for F

amili

es

Tips on Web Content

Short, descriptive headings Bullets – easy to skim! Numbered lists when order matters Short sentences with no jargon Active voice for verbs Hyperlinks to provide more detail

16


Cre

atin

g B

right

er D

ays

for F

amili

es

Design, Organization

& Management

17


Cre

atin

g B

right

er D

ays

for F

amili

es

Effective documentation is well:

o Written

o Designed

o Organized

o Maintained

Key Points

18


Cre

atin

g B

right

er D

ays

for F

amili

es

Good Design

Supports the audience & objectives

Easy to understand & use

19

A

D

D I

E

Analyze

Design

Develop Implement

Evaluate

20

Design & Development Framework

22

Source: Survey conducted by IBOPE Zogby International for SlideRocket, in May 2011

32% of audiences have fallen asleep during a PowerPoint presentation 55% of snoozers have fallen asleep twice or more 20% would rather pay taxes or go to the dentist than view a PowerPoint

http://www.zogby.com/

http://www.sliderocket.com/

http://www.sliderocket.com/

*Source for technical: http://www.cypressmedia.net/articles/article/15/improving_the_appearance_of_your_technical_document

Make It Engaging

Technical Documents Web Content PowerPoint TM

+ user interface + graphics + video + audio + interactives

+ fonts + colors + contrast + infographics + interactivity

meaningful graphics supporting graphics

+ pie charts + graphs + frames + colors + icons

23

24

Source: elearninginfographics.com SH!FT

Sample Infographic

25

Source: elearninginfographics.com Allen Interactions

Sample Infographic


Cre

atin

g B

right

er D

ays

for F

amili

es

Make It Quality

Use a style guide to

standardize style elements and presentation conventions Use templates to ensure

consistency across sections

26


Cre

atin

g B

right

er D

ays

for F

amili

es

Evaluate

evaluateevaluateevaluate

Paraphrase Testing

Usability Testing

Controlled Comparative Studies

Source: http://www.plainlanguage.gov/howto/guidelines/FederalPLGuidelines

27

Organizing Makes (Dollars) & Sense

Example 2

Example 3

Example 4

Source: Kirkpatrick, D.L., & Kirkpatrick, J.D. (2007). Implementing the Four Levels, Berrett-Koehler Publishers.

Four Levels of Learning Evaluation

Level 4: Results

To what degree do targeted outcomes occur as a result of the learning event and workplace reinforcement?

Level 3: Behavior

Do participants apply what they learned in training once they return to work?

Level 2: Learning

Do participants acquire the intended knowledge and skills based on their participation in the learning event?

Level 1: Reaction

Do participants react favorably to a learning event?

29

Easy to Use Make It Easy to Use Make It Easy to Use

Organizing

According to information collated by Cottrell Research, employees spend too much time looking for information needed to support their work.

Makes (Dollars) & Sense

8 Number of

searches a typical worker makes to find information

1.8 Hours a day

searching and gathering

information

13% Since 2002,

increase in time spent searching for information

19.8% business time wasted

by employees searching for

information to do their job effectively

Example 2

Example 3

Example 4

Source: http://cottrillresearch.com/various-survey-statistics-workers-spend-too-much-time-searching-for-information/

30

31

Problem Slide Maintenance The Need for Maintenance

Don’t leave your documentation with potholes!


Cre

atin

g B

right

er D

ays

for F

amili

es

Maintenance Toolkit

Content updates change controls version control file management

Web updates Content updates + accessibility broken links for app updates browser compatibility analytics legal elements

When you need to update web code—document changes

32


Cre

atin

g B

right

er D

ays

for F

amili

es

Maintenance

Keep your documentation

to date so you don’t let your users

33

34

Summary

adds value!


Cre

atin

g B

right

er D

ays

for F

amili

es

Trends & Tools

35


Cre

atin

g B

right

er D

ays

for F

amili

es

Key Points Future trends in mobile learning

impact documentation design and delivery Online resources present new

channels for collaborative writing

36

37

197.4 million US Consumers use smartphones

Source: comScore Dec 2015

38

By 2020, Mobile devices will be the primary connection to Internet worldwide

Source: Pew Research Center (Welinske)

Channels: Blogs Wikis Authoring Tools Mobile Apps

Methods: Responsive Design Video Gamefication

39

Mobile Learning & Support

Tools

40

41

Chronicle

Writing & Collaborative Tools

Wikis & Blogs File Sharing

Web & Video Conferencing

Authoring Tools

Writing Apps

eLearning Tools

Adobe Captivate

Productivity Apps

Office Productivity MS Suite

Blog Documentation Website

42

43

Blog Support Website


Cre

atin

g B

right

er D

ays

for F

amili

es

Resources www.courtlandconsulting.com/ericsa2016 Presentation Training & Technical guide examples Infographic examples Writing style guide example Training evaluation tips Federal resource site for agencies

delivering digital services to the public Writing and collaborative tools handout

44

http://www.courtlandconsulting.com/ericsa2016


Cre

atin

g B

right

er D

ays

for F

amili

es

Review & Questions

Thank you for participating!!

45


Cre

atin

g B

right

er D

ays

for F

amili

es

Speakers

Cindy Holdren Marcia Witt Michelle Le Feve

Senior Consultant, Center for the Support of Families

Senior Consultant & Training Specialist, Courtland Consulting

Project Manager & Communication Analyst, Courtland Consulting

[email protected] [email protected] [email protected]

46


Cre

atin

g B

right

er D

ays

for F

amili

es

Copyright Considerations Graphics provided in this presentation are used under license from Shutterstock by the speakers or source materials cited where used. Exceptions are noted below:

Bitmojis are the property of each speaker

Tip icon: Artist dtafalonso under license CC Attribution-No Derivative 4.0

All rights reserved to their respective owners for product and company trademarks used in this presentation.

47

http://creativecommons.org/licenses/by-nd/4.0/



