Low-Cost Embedded UA Using DITA

Low-Cost Embedded UA Using DITA
@RayGallon at #LavaCon

DITA in a Startup!
What
we
did:
Design
a
content
strategy
Set
up
architecture
for
an
embedded
UA
system
Implement
a
first
version
of
the
UA
(data
model
and
content)
RAY
GALLON
@RayGallon
at
#Lavacon
C U LT U R E C O M Presentation
©
2014
Ray
Gallon

Total Cost
(consulting not included)
oXygen
license
(less
than
500
€)
Average
of
8
-‐
20
programmer-‐hours
per
month
during
the
project
(~8
months)
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
http://www.anywheresolutionsgroup.co.uk/wp-content/uploads/2012/08/Pound-coins.png

Case Study: The Product
Business Activity Monitoring (BAM)
software
Fits the space between Business
Process Management (BPM) and
Business Intelligence (BI).
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
Client descr ibes two
audiences:
IT
Management
Hard to sell – two
audiences that normally
don’t act together.

Before Proceeding, Decide
Modern software:
complex, powerful, perplexing
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
but
“I need to get this done, and NOW!.”

Before Proceeding, Decide
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
UA
limited
to
procedures
≠
help
with
contingent
needs.
“Which,
if
any,
procedures
do
I
need
to
use?”
Conceptual
topics
might
provide
insight
but…
…People
with
contingent
needs
=
no
time
for
long
texts
We
can
help
users
get
real
work
done
more
quickly
with
a
bit
of
decision
support.
h"p://mixturesrx.com/blog/wp5content/uploads/2011/08/
weighing_the_balance1.jpg?

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.
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
http://www.emuseumstore.com/assets/images/t-004b-the-thinker-small.jpg
http://www.sevenstorieshigh.com/wp-content/uploads/2014/04/Decisions.jpg

Core Principles for
Decision Support of Any Type
Begin
http://core-development.com/site/wp-content/uploads/2011/11/1-in.png
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
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

The Solution:
Double Embeddedness
Embed procedural User Assistance
directly into the Interface
Embed simple concepts
directly into the User Assistance
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon

Embedded User Assistance
for Noz Urbina’s Mother
5
problem:
GONE!
year
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
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
OBVIOUSLY,
SHE
COULD
HAVE
READ
THE
MANUAL–
BUT
WOULD
SHE
HAVE?
WOULD
SHE
5
year
problem:
GONE!
REMEMBER
NEXT
TIME?
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
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

Kanban Information:
Help Users Learn Your Software Fast
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
All
the
information
the
user
needs
and
only
the
information
s/he
needs.
Delivered
when
s/he
needs
it
(at
the
moment
s/he
has
real
work
to
do).
Embedded
in
the
software
itself,
so
that:
It’s
findable
when
needed.
If
not
needed,
it
stays
out
of
the
way.

Double Embeddedness using
Progressive Information Disclosure
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
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/

Example: Business Process Dashboard –
Order Fulfillment
User Interaction model: Progressive Disclosure
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon

Discovery Process
Expressed needs:
“Documentation” – not descr ibed in detail
Objective: make the software easier to
under stand for potential customer s.
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon

Discovery Process
Inter views with key player s reveal the
following non expressed needs:
A documentation philosophy
Content architecture
Help with a content str ategy for
the two audiences
Help with inter action design choices
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon

The Big Surprise
There are indeed, two audiences, but
IT isn’t one of them.
The real two audiences are:
Oper ational people
Str ategy people
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
!

The Two Audiences
▪ Oper ationals:
▪ Interested in day-to-day
problem solving
▪ Monitor ing, maintaining
SLA commitments
▪ Str ategics:
▪ Interested in str ategic and oper ational data that can be
extr acted from the processes
▪ Don’t have great desire to use the software “hands on.”
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon

The Two Audiences
▪ Each has a different
“expertise” relationship to
the software
▪ Each needs communication in
a different voice and tone!
▪ Interested in day-to-day problem solving
▪ Monitoring, maintaining SLA commitments
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
▪ Strategics:
▪ Interested extracted in strategic from the and processes
operational data that can be
▪ Don’t have great desire to use the software “hands on.”
▪ Operationals:

Chosen Tools
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
DITA
No
CMS
-‐
Use
existing
SVN
but
prepared
for
future
expansion
Editor:
oXygen
Output:
JavaHelp
(sorry)

Why DITA?
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
Opportunities
for
reuse,
despite
small
volume
Use
conditionality
to
target
material
for
each
audience
Opportunities
for
later
automation
Modularity
was
familiar
and
comfortable
for
programmers

Chosen Architecture:
Progressive Information Disclosure
Enhanced Tooltip
Link Yes
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
!
Expand
Multiple
tasks?
!
Task Pane
!
Concept
Pane
!
Task
Pane
!
Task
Pane
Tripane with TOC
No
Multiple Links
At Will
!
Task
Pane

DEMO
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon

Enhanced Tool Tip: a DITA Generic Topic
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
!
<shortdesc>
pops up on hover (Level 1)
<abbreviated-form>
Glossary entry -
no action in tool tip
<resourceid>
links to
GUI element <body> & <related-links>
displayed in
tool tip slideout (Level 2)

Process Query Task Topic
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
!
<abbreviated-form>
called from tool tip…
<shortdesc> & first <p>
reused from tool tip
…<keyref>
from Glossary pops up

Blending Concepts and Tasks:
Kanban Information meets DITA
ERROR:
I
used
concepts
to
introduce
&
lead
into
multiple
tasks:
Concept:
This
concept
explains
what
this
element
of
the
interface
is
about.
It
is
used
in
the
following
tasks:
Task
1 Task
2 Task
3 Task
4
Inappropriate
use
of
conceptual
information:
Not
good
cognitive
development
Not
good
Kanban
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon

Blending Concepts and Tasks:
Kanban Information meets DITA
BETTER:
use
DITA
<task>
topic
structure
to
deliver
concepts
where
most
useful
and
best
remembered
<task>
General
concepts
for
the
whole
task
<step> Step 1
<cmd> Do this
<context>
<stepresult> What happens after step execution –
can include why
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
<step> Step 2
<cmd> Do that
<info> Use to embed concepts for step

Example
!
<shortdesc>
(from tool tip)
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
<context>
First <p> comes
from tool tip

Use <choice> lists and <info>
to include conceptual information
<cmd>
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
<choices>
<info>

<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.
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon

Another Approach
Thanks to Nathalie Laroche and Ixiasoft
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
Tool
Tip
Level
1

When Will a Full CMS
Be Necessary?
Localization
into
three
or
more
languages
Development
of
complex
future
automation
possibilitieshttp://blog.monitor.us/wp-content/uploads/2012/07/content-management-
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon
system-cms.jpg

Futures
Specialized
versions
of
the
UA
targeted
to
specific
industries
Customization
available
to
professional
services
consultants,
tailored
to
specific
customer
needs
Customization
by
users
-‐
stored
on
server
(applet
that
allows
annotation,
shared
by
all
users
with
same
permissions)
Build
at
install,
to
get
local
terminology
RAY
GALLON
@RayGallon
at
#Lavacon
©
2014
Ray
Gallon

About Ray Gallon - The Humanist Nerd
Owner/Consultant,
Culturecom
–
specialist
in
business
process
improvement
through
communication
Research
collaborator
and
principal,
The
Transformation
Society,
a
new
research
and
training
institute
in
Barcelona,
Spain
• 20+
years
in
the
content
industries
with
startups
and
major
companies
such
as
G.E.
Healthcare,
IBM,
Alcatel,
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

What We Can Help You Do
Analyse your needs
Design a content strategy
Architect your user information and
communication
Capture value from your users
Webinars and training
Manage and adjust to change

Thank
Pass
me
your
buisness
card
Let’s
talk!
Email:
infodesign@culturecom.net
Google
Plus:
+Ray
Gallon
Twitter:
@RayGallon
LinkedIn:
Ray
Gallon
Presentation
©
2014
Ray
Gallon
RAY
GALLON
C U L T U R E C O M @RayGallon
at
#Lavacon
Portions of this presentation based on research by
the Transformation Society Research group.
Blog:
Rant
of
a
Humanist
Nerd
http://humanistnerd.culturecom.net
Thanks, Jack Molisani and Lavacon Team

Low-Cost Embedded UA Using DITA

Recommended

Recommended

More Related Content

What's hot

What's hot (6)

Viewers also liked

Viewers also liked (20)

Similar to Low-Cost Embedded UA Using DITA

Similar to Low-Cost Embedded UA Using DITA (20)

More from The Transformation Society

More from The Transformation Society (20)

Recently uploaded

Recently uploaded (20)

Low-Cost Embedded UA Using DITA