Embedded User Assistance Using DITA

RAY GALLONC U L T U R E C O M

Presentation © 2012 Ray Gallon all rights reserved

Embedding User Assistance with DITA

Member, Board of Directors

Wednesday, 8 May 2013


Research collaborator and principal, The Transformation Society, a new research and training institute in Barcelona, Spain

20 years in technical communication with major companies such as G.E. Healthcare, Alcatel, IBM, etc.

Member, board of directors, Society for Technical Communication (STC)

Past president, STC France

Award-‐winning radio producer and journalist – CBC, NPR, France Culture, etc. and former programme manager, WNYC-‐FM, New York Public Radio

About Me

Owner/Consultant, Culturecom – specialist in usability, content strategy, and user assistance for software

The Humanist Nerd


Presentation © 2012-‐2013 Ray Gallon all rights reserved

Before Proceeding, Decide

Modern software’s complexity, features, & power can leave users perplexed – often just when they

have some immediate, contingent need:

“I need to get this done, and NOW!.”



Before Proceeding, Decide

User assistance that is limited to procedures cannot help people with contingent needs.

They need to decide which, if any, procedures they need to use.

Long conceptual topics might provide insight.

But people with contingent needs are not going to wade through long texts.

We can help users get real work done more quickly with a bit of decision support.



Decision Support for Users

Two types of decision support in software:

Automated decision support aids

Information designed to inform the user's judgment, but not formalized into an automated system

In technical c

ommunication,

most of the ti

me

we do the latt

er type.



Core Principles for Decision Support of Any Type

Begin with users’ needs

Give priority to process over products

Link information between producers and users

Build connections across disciplines and organizations

Seek institutional stability

Design processes for learning

Source: U.S. National Research Council


http://www.peopleandplace.net/on_the_wire/2011/3/21/principles_for_effective_decision_support__national_research_council%2520read%252025%2520july%25202011

http://www.peopleandplace.net/on_the_wire/2011/3/21/principles_for_effective_decision_support__national_research_council%2520read%252025%2520july%25202011

http://www.peopleandplace.net/on_the_wire/2011/3/21/principles_for_effective_decision_support__national_research_council

http://www.peopleandplace.net/on_the_wire/2011/3/21/principles_for_effective_decision_support__national_research_council


Core Principles of Minimalism as Restated by JoAnn Hackos

Focus on an action-‐oriented approach(Users’ needs, process)

Ensure you understand the users’ world(Users’ needs, links and connections, institutional stability)

Recognize the importance of troubleshooting information (Users’ needs, links and connections, learning)

Ensure that users can find the information they need (Users’ needs, learning, links and connections)

Source: http://www.infomanagementcenter.com/Resources/eNews2012-‐12JHackos.pdf


http://www.infomanagementcenter.com/Resources/eNews2012-12JHackos.pdf









Is memorizing a procedure by rote necessary for competency?

STEP 1STEP 2STEP 3

DO THIS

DON’T DO THA

T

NOTE:WARNING!

Is it “minimal” if users need to go

back to the help repeatedly?How does a user know if s/he even

wants or needs to do this task?

Doesn’t it stand

to reason that

when “learning b

y doing,” we

include the con

cepts that help

the user gener

alize to similar

tasks?

John Carroll, who create

d minimalism,

said:

People using produ

cts are most

interested in getti

ng real work done

.

People best learn a

bout product use b

y

doing something ra

ther than reading

about something.



Not Just Minimal – Minimal and Meaningful

People best lea

rn about produ

ct use by doing

something and making co

nnections in th

e

process.

Learn by doing

– put the conce

pts

where they will be us

eful and

remembered.

It’s minimal and meaningful if one

look at one task helps us understand

many related tasks.It’s minimal and meaningful if one

quick look tells us we don’t need to

bother with this (or that we do).



The Solution: Double Embeddedness

Embed pr

ocedural

User Ass

istance

directly

into th

e

Interfac

e Embed simple concepts directly into the User Assistance



Embedded User Assistance for Noz Urbina’s Mother

5 year problem:

GONE!

Informa5on Architecture: Not hidden but out of the way when not needed

Content Strategy & Technical Wri5ng: Simplicity, voice, tone, Task structure, delivery format

Business Analysis solves a long-‐standing problem using content tools/methodologies



Embedded User Assistance for Noz Urbina’s Mother

5 year problem:

GONE!

Informa5on Architecture: Not hidden but out of the way when not needed

Content Strategy & Technical Wri5ng: Simplicity, voice, tone, Task structure, delivery format

Business Analysis solves a long-‐standing problem using content tools/methodologies

OBVIOUSLY, SHE COULD HAVE READ THE MANUAL– BUT WOULD SHE HAVE?WOULD SHE REMEMBER NEXT TIME?



Kanban Information: Help Users Learn Your Software Fast

We want to give the user all the information s/he needs and only the information s/he needs.

We want to deliver that information when s/he needs it – which implies, at the moment s/he has real work to do.

The logical conclusion is that user assistance needs to be embedded in the software itself, in such a way that:

The user can find it immediately, without excessive searching, if s/he needs it.

If s/he doesn’t need it, it stays out of the way.



Kanban Information: Help Users Learn Your Software Fast

For the most part, we’ve assumed that means procedures. Concepts are out -‐ too long, too messy, too irrelevant. The user wants to meet her or his contingent need.

Some users will infer underlying principles and concepts from repeated procedures. Others, however, will not, unless we point them to it in some way.

We want the user to understand the information in a way that s/he can apply it to other situations, without needing to call repeatedly on the user assistance.


...AND WHEN????


Integrated Competency Learning

Adapted by Dr. Neus Lorenzo from Phil Ball & Keith Kelly (2009) Ref: http://ow.ly/dLK8g & http://goo.gl/Ul3A2

+ Individually significantcontextualisation (contingency)

+Socio-‐cultural construction(information sharing, mentoring)

+Procedural Memorisation

+ Cognitive construction and process reasoning

+Code: Mastery of the language, interface, iconography...

+Thematic knowledge(SME)

User Learning Space

WHERE IN THIS SPACE DO YOU WANT YOUR USERS?


http://ow.ly/dLK8g

http://ow.ly/dLK8g

http://goo.gl/Ul3A2

http://goo.gl/Ul3A2


Double Embeddedness using Progressive Information Disclosure

People understand a system better when you help them prioritize features and spend more time on the most important ones.

Progressive disclosure says:

Initially, show users only a few of the most important options.

Offer a larger set of specialized options upon request. Disclose these secondary features only if a user asks for them, meaning that most users can proceed with their tasks without worrying about this added complexity.

Andrea Ames coined Progressive Information Disclosure

Source: http://www.nngroup.com/articles/progressive-‐disclosure/


http://www.nngroup.com/articles/progressive-disclosure/







DEMO


!


Enhanced Tool Tip: a DITA Generic Topic

The <shortdesc> is what pops up on hover (Level 1)

The topic body and link are shown in the tool tip slideout (Level 2)

The <abbreviated-‐form> glossary entry is resolved without popup definition in the tool tip. It is rendered differently in the task topic. This is managed from the CSS

The <resourceid> element links the tool tip to the interface element. ID’s managed by the development team with tech comm input.


!


Process Query Task Topic

This time the abbreviated-‐form is resolved on hover…

…to pop up a <keyref> that points to a glossary entry

The <shortdesc> and first <p> are reused from the tool tip



Blending Concepts and Tasks: Kanban Information meets DITA

• We often use concepts to introduce & lead into multiple tasks:

Concept : Th i s concept explains what this element of the interface is all about. It is used in the following tasks:

Task 1 Task 2 Task 3 Task 4

• We don't know how else to do it, but this is an inappropriate use of conceptual information:• Not good cognitive development• Not good Kanban



Blending Concepts and Tasks: Kanban Information meets DITA

Why not use the DITA Task topic structure to deliver conceptual information where it will do the most good and be best remembered?

!


!


Example<shortdesc> (from tool tip)

<context>The first <p> comes from

tool tip



Use <choice> lists and <info> to include conceptual information

<cmd>

<choices>

<info>



<choicetable> offers another option

<cmd>

<choicetable>



<stepresult> used in <step> and nested <substep>

<substeps>

<substep> <stepresult>

<step> <stepresult>

All these elements are available after a <cmd>. Use the one that works best, semantically.



Another ApproachThanks to Nathalie Laroche and Ixiasoft

Tool Tip Level 1




Tool Tip Level 2




Tool Tip Level 1

Tool Tip Level 2






DITA Composite Topic – One Size Fits All

The composite topic begins, simply, with a <dita> tag. You can then insert any type of DITA topic, nested within it, including <reference> (not shown).

Use with great caution!



RAY GALLONC U L T U R E C O M

Email: [email protected]

Thank You!

Google Plus: +Ray GallonTwitter: @RayGallonLinkedIn: Ray Gallon

Visit my blog, Rant of a Humanist Nerd:http://humanistnerd.culturecom.net

Portions of this presentation based on research by

the Transformation Society Research group.

Member, Board of Directors


Technology

Embedded User Assistance Using DITA