embedded user assistance using dita
DESCRIPTION
Presentation at STC Technical Communication Summit, 2013 - #stc13. This presentation explores how to embed concepts in DITA task topics without breaking the DITA semantic structure. Includes theory and practical elements drawn from real current projects.TRANSCRIPT
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
Presentation © 2012 Ray Gallon all rights reserved
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
Wednesday, 8 May 2013
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!.”
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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.
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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.
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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.
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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).
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
The Solution: Double Embeddedness
Embed pr
ocedural
User Ass
istance
directly
into th
e
Interfac
e Embed simple concepts directly into the User Assistance
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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?
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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.
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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.
Wednesday, 8 May 2013
...AND WHEN????
Presentation © 2012 Ray Gallon all rights reserved
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?
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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/
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
DEMO
Wednesday, 8 May 2013
!
Presentation © 2012 Ray Gallon all rights reserved
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.
Wednesday, 8 May 2013
!
Presentation © 2012 Ray Gallon all rights reserved
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
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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?
!
Wednesday, 8 May 2013
!
Presentation © 2012 Ray Gallon all rights reserved
Example<shortdesc> (from tool tip)
<context>The first <p> comes from
tool tip
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
Use <choice> lists and <info> to include conceptual information
<cmd>
<choices>
<info>
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
<choicetable> offers another option
<cmd>
<choicetable>
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
<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.
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
Another ApproachThanks to Nathalie Laroche and Ixiasoft
Tool Tip Level 1
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
Another ApproachThanks to Nathalie Laroche and Ixiasoft
Tool Tip Level 2
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
Another ApproachThanks to Nathalie Laroche and Ixiasoft
Tool Tip Level 1
Tool Tip Level 2
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
Another ApproachThanks to Nathalie Laroche and Ixiasoft
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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!
Wednesday, 8 May 2013
Presentation © 2012 Ray Gallon all rights reserved
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
Wednesday, 8 May 2013