CHAPTER

Documentation and User Support (a.k.a. Help)

•· We learn by example and by direct experience because there ,, are real limits to the adequacy of verbal instruction .

Malcolm Gladwell

Blink : The Power of Thinking without Thinking, 2005

•· Our life is frittered away by detail. Simplify, simplify. ''

CHAPTER OUTLINE 14.1 Introduction

14.2 Shaping the Content of the Documentation

14.J Accessing the Documentation

14.4 Reading from Displays versus Reading from Paper

14.5 Online Tutorials and Animated Demonstrations

14.6 Online Communities and Other Avenues for User Support

14.7 The Development Process

Thoreau

485

486 Chapter 14 Documentation and User Support (a.k.a. Help)

14. 1 Introduction

Standardization and improvements in user interfaces have made computer applications easier to use, but using new interfaces is still a challenge. First-time computer users struggle to understand basic interface icons and actions as well as their tasks. Even for experienced users, learning advanced features and understanding novel task domains take commitment and concentration. Many users learn from someone else who knows the interface; others learn by trial and error, while others use the supp lied (typically online) documentation; and ye t others use outside sources, be they online or externally produced books. Over time, the reliance on formal user manuals, printed documentation, and tutorials has been less frequent. They are being replaced by customizable requests for help using the easier- to-use (and usually available) online search facilities. But some users still want this type of documentation as can be seen in the success of publishing groups .Yith series such as For Dumrnies, Missing Manuals, and Teach Yourself Visually.

Learning anything new is a challenge. Challenges can be joyou s and satisfying, but when it comes to leanung about compu ter systems, many people experience anxiety, frustration, and disappointment. Much of the difficulty stems directly from the poor design of the menus, displays, or instructions or simply from users' inability to easily determine what to do next. As the goal of providing universal usability becomes more prominent, online help services are increasingly necessary to bridge the gap between what users know and what they need to know.

Studies have show n that welJ-written and well-designed user manuals, on paper or online, can be effecti, re, bt1t toda y's users show little iI1terest m detailed manuals. Today's user mterfaces are expected to provide everythmg onlme, supplemented by quick -start gu ides and interactive tutorials that serve user needs for training and later on for contin ued reference. In fact, as displays appear in cars, phones, cameras, public kiosks, mobile de, rices, and elsewhere, ubiquitous and customizab le onlme help should be the norm. Increasing atten­ tion is bemg paid to improvmg user -interface design, but the comp lexity and diversity of interactive applications are also growing. Evidence suggests that ther e will always be a need for suppl emental materials that aid users in various formats (though the use of prmted manuals seems to be fadmg).

There are diverse ways of providmg guidance to users online, rangmg from a simple pop-up box (often called a tool tip, ScreenTip, or balloon help) to more advanced assistants and wizards. Most user interfaces have frequently asked questions (FAQs) and lively user communities that provide a more "grassroots" type of he lp and support. These communities are often supported or spon­ sored by companies to enable users to solve problems and provide product

14.2 Shaping the Content of the Documentation 487

See also:

Chapter 5, Evaluation and the User Experience

Chapter 8, Fluid Navigation

Chapter 11, Communicat ion and Col laboration

Chapter 15, Information Search

improvements. This user assistance may be available through formal online and structured user communities and newsgroups or more informal e-mail, chat, and instant messaging. A broad variety of formats and styles are used to meet the ever-present need for documentation and user support (Earle et al., 2015).

This chapter starts by discussing shaping the contents of documentation including writing for the web (Section 14.2) and then continues with accessing the documentation (Section 14.3). Section 14.4 explores the differences found reading from displays versus reading from paper. Next, tutorials and demon­ strations are discussed in Section 14.5, and online communities for user assis ­ tance and support (Section 14.6) are reviewed. The chapter closes with a brief section on the de, relopment process for user documentation (Section 14.7).

14.2 Shaping the Content of the Documentation

Traditional training and reference materials for computer systems were paper manuals, frequently left to the most junior member of the development team as a low-effort task to be comple ted at the end of the project. As a result, the manuals often were poorly written, were not suited to the users' backgrounds, were delayed or incomplete, and were tested inadequately if at all. Documentation has been referred to as "The Cinderella of Information Systems" (van Loggem, 2013). Today, managers recognize that designers may not fully understand the users' needs, that system developers might not be good writers, and that it takes time and skill to write effective documentation. They have also learned that testing and revision must be done before widespread dissemination and that system success is closely coupled to documentation quality. Users show little interest in reading manuals or documentation from cover to cover; their interest is focused on gathering information or completing a task (Redish, 2012). Content is now considered important enough that it has morphed into its own field, with books and guides about writing good content (Redish, 2012; Handle y, 2014). Writing content exclusively for the web has its own gu idelines (see Section 14.2.2).

488 Chapter 14 Documentation and User Support (a.k.a. Help)

Many users are technologically sophisticated. There is no appeal to reading or brow sing through many page s of documentation; users want to get going quickly with their technology products. Users expect an easy learning curve and the actions to perform the tasks at har1d to be easy to find and discover. Only with the most sophisticated computer systems is there a 11eed or desire for extensive training and long start -up times. Users want quick -start guides (Fig. 14.1), easy -to-navigate material, and lots of examples (Novick and Ward, 2006a); they also want content on tl1eir preferred medium including, video and audio, topic -based information, embedded help, animations, and 3-D graphics (Hackos, 2015) Some of these attributes are difficult to produce in general documentation for a wide-ranging audience.

Quick Start Guide New to OneNote 2016 or upgrading from a previous version? Use this guide to learn the basics.

Quick Acc:ess loolblf Kiecp .._._ OOll'ffl$nd5

p,ll'fNlllll'ltlf•iobla.

llq,lett dw ribbon Stt ""-' OneHolle 2016 c.i do bef dicb,g ttwe ribboft w.wo~-•…,,.._'°°"-

DIK- conlf'XIU.1,1 tonWIWKh Sdect,ny,-tcl … ~t.abteto _,fldcl .. ~~ 1CIOIII.

I] Office

Shareyoiwworkwi th~

$,gnlft..-itl'l-,O.,<loi.id:l((Oul'll'"f'N""""' kldwe'JOJl'M:Wk'll'llhoeha~

,,.., ,. , ,, ,, — ,a::-e .. ~ . .J ,_ – ·- .. _ ·- …. .,…. , ,, ..

C -· .,, ·- "':"' .. — , , 11-•• %•£ • • )I. ………. , – -~ —

r ,a .. – •• –· —–·-

Nowt,oolq: Li~ Od:: ltle 1'11:Jtdiot,l( Nffle lo -11:h bet-. IICllrboolcs Of

cick the FW' icon to biep the — ~ lt<t 01 fll<M' ,.. .,. .. .

Gd; or d,.g h gnpper 10 Nlcftdal'ClletoMkcto, r,,o,,,e11t, ot r,ght-dc:kc fot _,,.,,..

~o…– Microsoft

FIGURE 14. 1

… …..

+ f•,!("'lf.'O!~P!ln ·-·-·–. -~——· . __ .. _ … ..,,_

* ~ ~–J'IM ___ ………….. ·•—, ___ … w,.._ Rnbot Nocit ( OM.-inrn

.,__ ___ CRglheedgetotNloenotec

fll the pogeor~thetnbre f,-,ne tomo¥eit~

T~ any,t,fl«e on• ~

— Oneffote fled:'eQff4$ wi,c:~•" …. ""'Y' INIOCntr~-.

, ……. ;7

' '• -~-~~ … …… —·-

Hide 1he ,llbon

Need – -? Oid:the-lo tum the nbbon on …..

•lt'tantJy f',nd ~Y'hi119 s-m the wnent page 0, ..

notttioob .t ontc.-w:I nwi· gMethefewlb…ihet1w.

Kold)ootthgci Od:1hesetlhltoMotch ~P'flll5"'the curreo-.,-..11:-bot.A~

This particu lar quick-start guide for Microsoft OneNote 2016 points out common actions for users. Its goal is to minimize the learning curve for users upgrading from a previous version. The quick-start guide is four pages long; this is the first page . Explanations are provided for the tool bar and the ribbon in addit ion to other commonly used features.

14.2 Shaping the Content of the Documentation 489

14.2.1 Organization and writing style

Designing documentation is a chaUenging endeavor. The author must be knowl­ edgeable about the technical content; sens itive to the background, reading level, native language, and intellectual ability of the reader; and skilled in writing lucid prose. Assuming that the author has acquired the technical content, the primary job in creating documentation is to understand the readers and the tasks that they must perform.

A precise statement of the instructional objectives is an invaluable guide to the author and the reader. The sequencing of the instructional content should be governed by the reader's current knowledge and ultimate objectives. Precise rules are hard to identify, but the author should attempt to present concepts in a logical sequence in increasing order of difficulty to ensure that each concept is explained before being used in subsequent sections, to avoid forward refer­ ences, and to construct sections that contain approximately equal amounts of new material. In addition to these structural requirements, the documentation should have sufficient examples and complete sample sessions. These guide­ lines are valid for manuals and other documentation that is typicall y read sequentially. When writing for sophisticated interfaces, where approaches are not sequential, new techniques may need to be tried. A mantra of many techni­ cal writers is "write once, publish many places," as they are aware that the con­ tent will be published in multiple formats and in multiple places. Companies such as Acrolinx can help the writer with this process.

Before starting to write any documentation, it's important to thoroughly understand who the intended users are and how and where the documentation will be used. Frampton {2008) sugges ts numerous questions that should be con­ sidered: Who is the intended audience for the documentation? What are the market expectations for the documentation? What amount of the budget has been allocated for it? Are some components of the documentation considered essential or required and others supplemental or nice to have? How will the documentation be used? Will it be used once and thrown away or used repeat­ edly over a long period of time? What is the reading level of the potential users? Is the documentation written in their nati ve lang uage? What is the intended user's level of comfor t w ith techno logy? Following the user-centered design process is a good way for the documentation authors to communicate and dis­ cuss requirements with the users, and this approach will yield better-designed documentation ..

Redish (2012) encourag es authors to divide documentation int o topics and subtopics. Topics can be organized according to time or sequence, tasks, people, type of information presented, or questions people ask. Today's online world is one of agile information development, and technical information development is und ergoing many changes (Hackos, 2015). Development cycles are short, and competition is fierce. A trend in technical communication since the late 1990s is

490 Chapter 14 Documentation and User Support (a.k.a. Help)

to write documentation based on standards, such as Darwin Information Typing Architecture (DITA). The DITA standard (http:/ /dita.xml.org) emphasizes developing and organizing content based on three information types: concept, task, and reference. These information types represent "chunks" of content that can be reused and, importantly, published across multiple platforms (Fig. 14.2). Adhering to a standard also enables sharing of content between different groups within and outside an organization. For example, a training group can reuse content from tl,e techni cal writing group.

Users interact with the documentation on several different cognitive levels. They go to the documentation to find information that is relevant to accomplish ­ ing a task. They need to understand what the documentation is explaining, and they then need to apply that understanding to the task that caused them to consult the documentation in the first place. In this process, there are lots of places for misunderstandings and increased cognitive load. Additionally, users may already be in a stressful situation and frustrated because the interface is not letting them accomplish their task.

The choice of words and their phrasing is as important as the overall structure. A poorly written sentence mars a well -designed manual, just as an incorrect note mars a beautifully composed sonata. The Elen1ents of Style (Strunk et al., 2000) and On Writing Well (Zinsser, 2006) are two class ic references. Other more

Darwin Information Typing Architecture (DITA) Mapping

Data source topics

1

2

3

4

5

IT) i————- –4 … ►

FIGURE 14.2

Compiled help

CFM

Website HTML

Print

PDF

The documentation content is organized as single source topics created, during the authoring process, with the intention of reuse. The various documentation end produc ts (compiled help, website, print) are mapped from the various combinations of the single source topics.

14.2 Shaping the Content of the Documentation 491

recently updated books on writing include Everybody Writes (Handley, 2014), Letting Go of the Words (Redish, 2012), Every Page Is Page One (Baker, 2013), Designing for Digital Reading (Pearson et al., 2014), Conversation and CommunihJ (Gentle, 2012), Designing Information (Katz, 2012), The Essentials of Technical Communication (Tebeaux and Dragga, 2014), Solving Problems in Technical Con1n1unication Gohnson -Eilola and Selber, 2013), and The Sense of Style (Pinker, 2014). Specialized books such as The Global English Style Guide (Kohl, 2008) can help with writing for global audie11ces, and ReaderCentric Writing for Digital Media (Hailey, 2015) provide s a theoretical framework to improve online media content. Style guides for organizations represent worthy attempts at ensuring consistency and high quality (see Chapter 1). But, of course, no set of guidelines can tum a mediocr e writer ir1to a great writer. Writing is a highly creative act; effective content and documentation writers are needed.

There are numerous resources available for professional communicators, with an emphasis on technical communication. Formal courses and degree programs exist as well as specialized institute s and workshops. Books (as mentioned above) exist to explain technique s for writing documentation (and specifically web content) as well as formal pedagogy. The IEEE (through its Professional Communication Society), the ACM's Special Interest Group on Design of Communication (SIGDOC), and the Society for Technical Communi­ cation (STC) pro vide theore tical publi cation s as '"'ell as information of a mor e practical nature. Redish (2010) discusses the intertwining of technical communi ­ cation and usability, how both fields can and do learn from one another , and how the combination adds strength to both. Studies are also und er way to see how crowd sourcing can be us ed to impr ove writing (Bernstein et al., 2015).

14.2.2 Writing for the web When writing for the web, it is important to be aware of the differences from conventional writing and reading practice s. When the web is utilized on mobile devices, screen sizes can be small and screen real estate is critical, so the designer needs to be aware and make every word count. In journalism, there is the ongo ­ ing discussion about the pros and cons of the inverted pyra1nid style of writing. In the inverted pyramid the most important information or the main point comes first, then the remaining information follows with the least important informa ­ tion at the end (Redish, 2012). This works well for the web since it has been shown that users typically don't scroll.

Gaining a better und erstanding of us ers' reading patt erns in online environ ­ ment s is important. A study using eye-tracking and displaying where and how users viewed a webpage clearly shows users read following an F-shaped pattern (Fig. 14.3). This indicates that users do not read online text word by word. The beginning paragraph s should contain the most important information; after reading them, us ers tend to contint1e to scan down the left side of the pag e, so

492 Chapter 14 Documentation and User Support (a.k.a. Help)

FIGURE 14.3 In heat maps from the eye-tracking study, red indicates the area w here the use r looked mos t , yellow indica tes fewer views, and blue ind icates the fewest views. Gray is used for areas t hat were not viewed. The image on t he left is f rom an article in the "About Us" section of a corpora te website, the center image is a product page on an e-commerce website, and the image on the right is from a search engine results page (https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content/ and Ja kob Nielsen).

the words they see there should also carry the important information content (Nielsen, 2006).

Another approach coined by LesLie O'Flahavan (founder of ewriteonline. com) is "a bite, a snack, and a meal." This describes the varying amoun t of content presented to the reader. A bite is the headline or main point. A snack is a bit more detail and perhaps an article summary or some cogent points. A meal is the entire article. The way content is read is changing, and that affects how content is written. Now readers not only view the content but also want to easily share the content with friends, coworkers, and so on. Web content has to be fluid across platforms.

Box 14.l offers some design maxims to follow when writing for the web. It is important to understand the reason the user is corning to the website. Users may be coming for content; they are not there to reflect upon the design. Users come for information to answer a question or to help them complete a task; that information should be easy to find and easy to understand. Think about every time the web content is accessed as the beginning of a conversation started by the site visitor (user). Obtain as much information as you can about your users.

14.3 Accessing the Documentation 493

BOX 14.1 Helpfu l advice when writing for the web (Redish, 2012).

• Break your text into short sections with clear headings.

• Start with your key message.

• Write short sentences and short paragraphs.

• Use lists and tables-tables may not work well for mobile devices.

• Write meaningful links (do not use "click here") .

• Illustrate your content.

14.3 Accessing the Documentation

Studi es in the past have confirm ed that well-des igned documentation can be very effective. In spi te of improvements, however, most users avoid user manuals if they can. If users read the documentation, they "sa tisfice," skip, scan, and skim (Mehlenbacher, 2009). Users typically do not want to sift throu gh volumin ous user manuals that can be difficult to navigate. Instead, they want quick and easy access to instruc tions for the speci fic tasks they are trying to carry out (Redish, 2012). Even when problems arise, man y users are reluctant to consult written documentation and may do so only as a last resort. Although guidelines have been applied to improve the design of online components to take advantage of their unjque media, studi es still show low use of docwnenta­ tion (Novick et al., 2007).

Standard formats such as HTML Help, Java Help, and DITA have stimulated development of a growing number of software tools to generate help files, such as Adobe RoboHelpTM (http://adobe.com/products/robohelp.html) and oXygen WebHelp (https:/ /www.oxygenxm l.com /xm l_author/webhelp.html). These tools facilitate coordination among teams of authors in creating interactive online help in multiple formats for multiple platforms.

Documentation is often placed online for good reasons. The issue becomes one of making the best use of the online environment when accessing the material. Multiple ways are available to search and traverse the online information differently from paper documentation. One feature of online documentation is the ability to offer pop-up help as well as customized help for var ious user population s, such as users with dis abilities, international users, and user s in varying age ranges.

494 Chapter 14 Documentation and User Support (a.k.a. Help)

14.3. 1 Online documentation

The low production and shipping costs of CD-ROMs initially encouraged hardware suppl iers to produce online documentation that was an exac t duplicate of the paper documentation and/ or manuals. Most manufacturers toda y put their user documentation directly online and no longer create sup ­ porting paper-based documentation. Modern designs assume that online documentation or web-based documentation will be available, usually with standard browsing interfaces to reduce learning effort. For mobile devices, small displays limit the possibilities, but providing helpful instructions on the device to complement printed user documentation should still be a prior­ ity. To keep this information up to date, users are often referred to the manu­ facturer's website, where downloadable manuals and other forms of documentation, such as frequently asked questions (FAQs), are often readily available.

A vital feature for online documentation-especially manuals-is a properly desigr1ed table of contents that can remain visible to the side of the displayed page of text. Selection of a chapter or other entry in the table of contents (Fig. 12.5) should immediately result in the appropriate page being displayed. Use of expanding or contracting tables of contents (the common use of the plus and minus signs) or multiple panes to show several levels at once car1 be benefi­ cial. Being able to conveniently and easily navigate using hyperlinks through large volumes of online documentation is vital for the user.

Although they are frequently generated from the same source document (usually an XML or XHTML document), online documentation now tends to differ from paper documentation, benefitting from all the physical advantages, navigation features, and interactive services available online (see Box 14.2). On the other hand, paper documents have traditionally housed supplemen tar y local information that is of ten written in margins or included on slips of paper stuck in at the appropriate pages. Some printed documenta­ tion remains pristine, neatly encased in its original shrink -wrapped packag ­ ing, but dog-eared, stained, and worn pages are often seen on well-used documentation. Online documentation that allows for local annotations, syn­ onyms, alterna te phrasing, or tran slations has enhanced value . Addi tional desirable services include support for bookmarking and automatic history keeping, which allows backtracking. Designers will be most effective when they design online documentation to fit the electronic medium and take advantage of text highlighting, color, sound, animation, and string search with relevant feedback. In some cases, provisions may be needed to provide the documentation offline, if access is not allowed outside of internal net ­ works. Researchers caution that words should be treated as valuable com­ modities and used spar ingly in documentation, whether in printed form or online (Redish, 2012).

14.3 Accessing the Documentation 495

BOX 14.2 Advantages of online documentation.

• Physical advantages: Available whenever on web-connected electronic device, can 't get lost or misplaced, physica l workspace not needed, can be updated rapid ly.

• Navigation features: Can provide inde x and other search facilities, can link to other external materia ls and sources.

• Interactive services: Can bookmark, annotate, and tag; can inc lude graphics, sound, color, and animation; screen read ers or other tools can be provided for users with disabilities.

14.3.2 Online help Users typ ically seek out help in solving spec ific probl ems and will wa nt to go directly to the informa tion that is needed. The traditional approach with online documentation is to have users type in or select a help-menu item; the system then disp lays a list of alphabetically arranged topics that can be clicked on to read a paragr aph or more of helpful information. This method . can work, but it is often frustrating for those users who are not sur e of the correct terms to use to search for information on the tasks they wish to accomplish . They may see several familiar terms (search, query, select, browse, find, reveal, display, info , or view) but not know which one to select. Worse still, there may not be a single command that accomplishes the task, and there is usually litt le information about how to assemble actions to perform tasks (such as converting graphics into a different format). Online help that offers concise descriptions of the inter­ face icons and actions (Fig. 14.4) is probably most effective for intermittent knowledgeable users; it is likely to be less useful for novices, ,-vho have more need for tutorial training.

Sometimes simp le lists-for example, of keyboard shortcuts, menu iten1s, icon glossaries, or n1ouse shortcuts–can provide the necessary information. Each item in the list might have an accompanying feature description. However, many designer s recognize that such lists can be overwhe lmir1g and that users usually want guidance for accomp lishing their specific intended tasks (for example, printing on envelopes).

The online help and suppor t center found with most Microsoft products offers man y ways of finding relevant articles, called topics. Users can browse an organized table of contents that lists the topics hierarchical ly or search the text of the articles. Finally, Microsoft's current approach allows users to

496 Chapter 14 Documentation and User Support (a.k.a. Help)

• • Migrat ion Process

Tables Relationshi s TOs Value lists CFs

Toblos. 5 ./ New Table Source Original Table ~,_,,. ____ ns_, ___ __,~ Contac~

FileMaker 14

Step 2: Import Layouts from FlleMaker Advanced database(s).

Click lhe Layouts tab, click the Layout Batch Import bullon .

Step 3: Click lhe Scripts tab.

Select all of lhe SctiplMaker Scripts within FileMaker Advaneed, oopyto clipboard.

Click lhe Add Scripts button to copy the scrip~ from the

Stop 5

Remap Objects

ln Prog,oss

Inc.

FIGURE 14.4

Members FileMaker 14 lbl Assets lbl assets FileMaker 14 tbl_Maintenance_Reoor<J

FIOlds. 70

ID 1 2 3 5 7

Original Fieldname 10 Model Item Category f".nc::I

Step 2

~-·· –_, -· -·

Got Layouts

Co~ted

Stop 6

+ j

Create CFs, Tabios , Table Occ urrences

Not Started __ ….,

FileMaker 14

) PK Auto-Increment 1 1

0 0 0 0 0 0 n n