Download - Low-Cost Embedded UA Using DITA
@RayGallon at #LavaCon
Low-Cost Embedded UA Using DITA
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@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 GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Total Cost (consulting not included)
oXygen license (less than 500 €)
Average of 8 -‐ 20 programmer-‐hours per month during the project (~8 months)
http://www.anywheresolutionsgroup.co.uk/wp-content/uploads/2012/08/Pound-coins.png
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Case Study: The ProductBusiness Activity Monitoring (BAM) software
Fits the space between Business Process Management (BPM) and Business Intelligence (BI).
Client describes two
audiences: IT Management
Hard to sell – two audiences that normally don’t act together.
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Before Proceeding, Decide
Modern software: complex, powerful, perplexing
but
“I need to get this done, and NOW!.”
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
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.
Before Proceeding, Decide
h"p://mixturesrx.com/blog/wp5content/uploads/2011/08/weighing_the_balance1.jpg?
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
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
Decision Support for Users
In technical communication, most of the time we do the latter type.
http://www.emuseumstore.com/assets/images/t-004b-the-thinker-small.jpg http://www.sevenstorieshigh.com/wp-content/uploads/2014/04/Decisions.jpg
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Core Principles for Decision Support of Any TypeBegin 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 learningSource: U.S. National Research Councilhttp://core-development.com/site/wp-content/uploads/2011/11/1-in.png
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
The Solution: Double Embeddedness
Embed procedural User Assistance
directly into the Interface
Embed simple concepts directly into the User Assistance
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
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
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
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?
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Kanban Information: Help Users Learn Your Software Fast
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.
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
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/
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Example: Business Process Dashboard – Order Fulfillment
User Interaction model: Progressive Disclosure
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Discovery Process
Expressed needs:
“Documentation” – not described in detail
Objective: make the software easier to
understand for potential customers.
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Discovery ProcessInterviews with key players reveal the following non expressed needs: A documentation philosophy Content architecture Help with a content strategy for the two audiences
Help with interaction design choices
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
The Big Surprise
The real two audiences are: Operational people Strategy people
!There are indeed, two audiences, but
IT isn’t one of them.
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
The Two Audiences
▪ Strategics: ▪ Interested in strategic and operational data that can be extracted from the processes ▪ Don’t have great desire to use the software “hands on.”
▪ Operationals: ▪ Interested in day-to-day
problem solving
▪ Monitoring, maintaining SLA commitments
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
▪ Strategics: ▪ Interested in strategic and operational data that can be
extracted from the processes ▪ Don’t have great desire to use the software “hands on.”
▪ Operationals:
▪ Interested in day-to-day problem solving
▪ Monitoring, maintaining SLA commitments
▪ Each has a different “expertise” relationship to
the software
▪ Each needs communication in
a different voice and tone!
The Two Audiences
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Chosen Tools
DITA No CMS -‐ Use existing SVN but
prepared for future expansion
Editor: oXygen
Output: JavaHelp (sorry)
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Why DITA?
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
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Chosen Architecture: Progressive Information Disclosure
!Expand
Enhanced Tooltip
Multiple tasks?
!Task Pane
!Concept
Pane
!Task Pane
!Task Pane
Tripane with TOC
No
YesLink
Multiple Links
At Will
!Task Pane
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
DEMO
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
!
Enhanced Tool Tip: a DITA Generic Topic<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)
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
!
Process Query Task Topic
<abbreviated-form> called from tool tip…
<shortdesc> & first <p> reused from tool tip
…<keyref> from Glossary pops up
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
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 GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
<task>
BETTER: use DITA <task> topic structure to deliver concepts where most useful and best remembered
Blending Concepts and Tasks: Kanban Information meets DITA
<step> Step 2 <cmd> Do that
<info> Use to embed concepts for step
<step> Step 1 <cmd> Do this
<stepresult> What happens after step execution – can include why
<context> General concepts for the whole task
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
!
Example
<context> First <p> comes
from tool tip
<shortdesc> (from tool tip)
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Use <choice> lists and <info> to include conceptual information
<cmd>
<choices>
<info>
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
<choicetable> offers another option
<cmd>
<choicetable>
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
<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 GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Another Approach Thanks to Nathalie Laroche and Ixiasoft
Tool Tip Level 1
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Tool Tip Level 2
Another Approach Thanks to Nathalie Laroche and Ixiasoft
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Another Approach Thanks to Nathalie Laroche and Ixiasoft
Tool Tip Level 2
Tool Tip Level 1
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
Another Approach Thanks to Nathalie Laroche and Ixiasoft
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
When Will a Full CMS Be Necessary?
Localization into three or more languages
Development of complex future automation possibilities
http:/
/blog
.mon
itor.u
s/wp-c
onten
t/uplo
ads/2
012/0
7/con
tent-
manag
emen
t-syst
em-cm
s.jpg
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
FuturesSpecialized 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
@RayGallon at #LavaCon
About Ray Gallon - The Humanist Nerd
• 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
Research collaborator and principal, The Transformation Society, a new research and training institute in Barcelona, Spain
Owner/Consultant, Culturecom – specialist in business process improvement through communication
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@RayGallon at #LavaCon
Thank
Email: [email protected]
Google Plus: +Ray Gallon Twitter: @RayGallon
LinkedIn: Ray Gallon
Presentation © 2014 Ray Gallon
RAY GALLONC U L T U R E C O M @RayGallon at #Lavacon
Pass me your buisness card Let’s talk!
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