The presentation by Ray Gallon discusses the complexities of modern software and emphasizes the need for embedded user assistance that is easily accessible to users when they have immediate tasks, rather than relying on lengthy manuals. It introduces the concept of 'double embeddedness' to integrate procedural assistance and relevant concepts within the software interface to enhance user experience. Core principles and strategies for effective decision support and learning processes are explored, highlighting the importance of understanding user needs and minimizing unnecessary information.

1. RAY
GALLON
C 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

2. 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

3. 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

4. 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

5. 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 communication, most of the time
we do the latter type.
Wednesday, 8 May 2013

6. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Core Principles for
Decision Support of AnyType
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

7. 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

8. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Is memorizing a procedure by rote necessary
for competency?
STEP
1
STEP
2
STEP
3
DO
THIS
DON’T
DO
THAT
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
by
doing,”
we
include
the
concepts
that
help
the
user
generalize
to
similar
tasks?
John
Carroll,
who
created
minimalism,
said:
People
using
products
are
most
interested
in
getting
real
work
done.
People
best
learn
about
product
use
by
doing
something
rather
than
reading
about
something.
Wednesday, 8 May 2013

9. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Not Just Minimal – Minimal and Meaningful
People
best
learn
about
product
use
by
doing
something
and
making
connections
in
the
process.
Learn
by
doing
–
put
the
concepts
where
they
will
be
useful
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

10. Presentation
©
2012
Ray
Gallon
all
rights
reserved
The Solution: Double Embeddedness
Embed
procedural
User
Assistance
directly
into
the
Interface Embed simpleconcepts directlyinto theUser Assistance
Wednesday, 8 May 2013

11. 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

12. 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

13. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Kanban Information:
Help Users LearnYour 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

14. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Kanban Information:
Help Users LearnYour 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

15. ...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
significant
contextualisation
(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

16. 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

17. Presentation
©
2012
Ray
Gallon
all
rights
reserved
DEMO
Wednesday, 8 May 2013

18. !
Presentation
©
2012
Ray
Gallon
all
rights
reserved
EnhancedToolTip:
a DITA GenericTopic
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

19. !
Presentation
©
2012
Ray
Gallon
all
rights
reserved
Process QueryTaskTopic
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

20. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Blending Concepts andTasks:
Kanban Information meets DITA
• We
often
use
concepts
to
introduce
&
lead
into
multiple
tasks:
Concept:
This
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

21. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Blending Concepts andTasks:
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

22. !
Presentation
©
2012
Ray
Gallon
all
rights
reserved
Example
<shortdesc>
(from
tool
tip)
<context>
The
first
<p>
comes
from
tool
tip
Wednesday, 8 May 2013

23. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Use <choice> lists and <info> to
include conceptual information
<cmd>
<choices>
<info>
Wednesday, 8 May 2013

24. Presentation
©
2012
Ray
Gallon
all
rights
reserved
<choicetable> offers another option
<cmd>
<choicetable>
Wednesday, 8 May 2013

25. 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

26. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Another Approach
Thanks to Nathalie Laroche and Ixiasoft
Tool
Tip
Level
1
Wednesday, 8 May 2013

27. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Another Approach
Thanks to Nathalie Laroche and Ixiasoft
Tool
Tip
Level
2
Wednesday, 8 May 2013

28. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Another Approach
Thanks to Nathalie Laroche and Ixiasoft
Tool
Tip
Level
1
Tool
Tip
Level
2
Wednesday, 8 May 2013

29. Presentation
©
2012
Ray
Gallon
all
rights
reserved
Another Approach
Thanks to Nathalie Laroche and Ixiasoft
Wednesday, 8 May 2013

30. Presentation
©
2012
Ray
Gallon
all
rights
reserved
DITA CompositeTopic –
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

31. Presentation
©
2012
Ray
Gallon
all
rights
reserved
RAY
GALLON
C U L T U R E C O M
Email:
infodesign@culturecom.net
Thank
You!
Google
Plus:
+Ray
Gallon
Twitter:
@RayGallon
LinkedIn:
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