low-cost embedded ua using dita
DESCRIPTION
My Presentation for the Lavacon 2014 conference. It's a case study on how I implemented a DITA-based, embedded User Assistance system in a software project, at almost no cost (other than my time). We did this despite the fact that the overall volume of information was low, and the company is a small one. The reasons for choices are explored, and there are examples of DITA code.TRANSCRIPT
![Page 1: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/1.jpg)
@RayGallon at #LavaCon
Low-Cost Embedded UA Using DITA
![Page 2: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/2.jpg)
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)
![Page 3: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/3.jpg)
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
![Page 4: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/4.jpg)
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.
![Page 5: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/5.jpg)
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!.”
![Page 6: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/6.jpg)
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?
![Page 7: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/7.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
![Page 8: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/8.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
![Page 9: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/9.jpg)
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
![Page 10: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/10.jpg)
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
![Page 11: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/11.jpg)
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?
![Page 12: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/12.jpg)
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.
![Page 13: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/13.jpg)
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/
![Page 14: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/14.jpg)
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
![Page 15: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/15.jpg)
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.
![Page 16: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/16.jpg)
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
![Page 17: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/17.jpg)
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.
![Page 18: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/18.jpg)
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
![Page 19: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/19.jpg)
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
![Page 20: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/20.jpg)
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)
![Page 21: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/21.jpg)
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
![Page 22: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/22.jpg)
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
![Page 23: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/23.jpg)
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
DEMO
![Page 24: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/24.jpg)
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)
![Page 25: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/25.jpg)
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
![Page 26: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/26.jpg)
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
![Page 27: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/27.jpg)
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
![Page 28: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/28.jpg)
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)
![Page 29: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/29.jpg)
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>
![Page 30: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/30.jpg)
RAY GALLONC U L T U R E C O M Presentation © 2014 Ray Gallon
@RayGallon at #Lavacon
<choicetable> offers another option
<cmd>
<choicetable>
![Page 31: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/31.jpg)
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.
![Page 32: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/32.jpg)
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
![Page 33: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/33.jpg)
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
![Page 34: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/34.jpg)
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
![Page 35: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/35.jpg)
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
![Page 36: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/36.jpg)
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
![Page 37: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/37.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
![Page 38: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/38.jpg)
@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
![Page 39: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/39.jpg)
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
![Page 40: Low-Cost Embedded UA Using DITA](https://reader033.vdocument.in/reader033/viewer/2022060106/547e8c15b4795984508b4b53/html5/thumbnails/40.jpg)
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