In this presentation we show how DITA can be used to power embedded user assistance systems with insights on collaboration between content development, interaction design and software development teams. A sample slide for embedded user assistance using Microsoft Silverlight is included.

1. Embedded User Assistance
NLDITA 2011
By Marc Speyer
www.sperotech.com

2. Agenda
Sperotech background
Traditional versus embedded help
Using DITA for embedded help
Implementation scenarios
Using Semantic layers
www.sperotech.com

3. Sperotech Background
Software and services company
Founded in 2009, located in Amsterdam
Specializes in solutions for user assistance
Traditional manuals and online help
Interactive (embedded) user guidance and support systems
Expertise (10+ years):
Design and implement information architectures
Content processes and workflow
XMetaL, Oxygen XML and FrameMaker authoring tools
CSS, XSLT and XSL-FO stylesheets, DITA Open Toolkit customizations
Develop and deliver end user trainings
Legacy content migration
User assistance RIA applications using technologies such as
Microsoft Silverlight, WPF, ASP.NET, ASP MVC, HTML and JavaScript
SharePoint and XDocs content management and collaboration systems
3
www.sperotech.com

4. TRADITIONAL HELP VERSUS
EMBEDDED
www.sperotech.com

5. Traditional online help is often not
effective
Most people do not
know about the existing help
want to ask for help
like to navigate in an additional tool
consult the help ahead of time
Most people
are usually busy with the task when they need help
want to be interrupted for as short time as possible
will expect useful information (and won't come back if not)
Source: Observations are from research and client projects
www.sperotech.com

6. Embedded user assistance
technology works better
Embedded user assistance works because
Assistance is there when the user needs it
It reduces the interrupt time
It is the proper type of information at the right place at the
right time
The user can still get background information offline
when there is time
www.sperotech.com

7. Useful for…
Manufacturers of
Medical devices
Measuring / Monitoring devices
Instrument panels
Software vendors
Desktop applications
Web application
Mobile phone and tablet apps
www.sperotech.com

8. Onboard versus offboard
How do What is this
I? all about?
What is What is
next? onboard, this?
integrated offboard,
and standalone
immediate
Why do I
How can I
need to do
experiment?
this?
Which What
should I should I
select? enter?
I have no time and need help now I have more time to read the help
www.sperotech.com

9. User Assistance Process View
Content Development HID Software Dev. Production
Topics
Maps Onboard
Styles Rules Online
Offline
Interaction
Metadata
Create Process User Assistance
Taxonomy / subject scheme CSS style properties UA integration subsystem
Controlled vocabulary (sw locators) XSLT /XSL-FO files Interactive dynamic help
Structured authoring tools Build scripts Traditional on-line help
Authoring guidelines Open Source tools e-books (PDF, ePub)
Validation & preview tools Rendering software (PDF) e-learning
www.sperotech.com

10. UA Stakeholders
Project
managers Legal staff
Be sure to include all
Requirements
analysts
stakeholders
Help desk
Users
UA Content developers
Requirements
Customers
(funders)
Process Field
support
Software
Developers
Manufacturing
Testers Sales &
Marketing
www.sperotech.com

11. USER ASSISTANCE USING
DITA
www.sperotech.com

12. DITA topics and specializations
DITA Topics and specializations
Root
Topic
(not used)
Base Concept Task Reference GlossEntry
(technical content)
UA Specializations Trouble-
Locator AlarmDesc Tasklist FAQ
(technical content, guided help) shooter
www.sperotech.com

13. Maps and reuse of task-maps
topic
Introduction topic
…
Task1
Online help
How to's Task2
How to perform a Task3
test rerun on the
test panel
Start conditions
Software
reference
QA parameters
www.sperotech.com

14. GlossEntry topic type
Benefits of using DITA's GlossEntry
topic type
It can provide explanations when
the online help is displayed
Can be used for both context
sensitive help & glossary index
It can be used to describe context
sensitive help at the UI control
level
It can educate the user of the
proper usage of terms, acronyms,
icons, short version, and
prohibited variants
Localization is as easy as localizing
DITA content
www.sperotech.com

15. IMPLEMENTATION
SCENARIOS
www.sperotech.com

16. Field Validation
Embedded User Assistance
Routine Tools ... Search: Search term
Client Data Client Sample
Sample ID: 17661
ID:
Name: Your name Sample type: Serum Priority: Normal
Address: Enter a valid
Your address ID Order date: 31-5-2011 ...
How to enter a valid id → > Collection date: 31-5-2011 ...
Zip: Postal code
Select Country < Therapist
Name: Dr. A. Utziniker Change..
Lookup samples Tests: Date
23-02-2010
05-04-2010
30-05-2010
www.sperotech.com

17. Embedded Help Topic
Embedded User Assistance
Routine Tools ... Search: Search term
Client Data
ID:
About Client Data
XYZ > Client > View Sample
Name: Your name
Lorem ipsum dolor sit amet, consectetuer adipiscing
Address: Your address elit. Maecenas porttitor congue massa. Fusce posuere,
magna sed pulvinar ultricies, purus lectus malesuada
>
libero, sit amet commodo magna eros quis urna. Nunc
Zip: Postal code viverra imperdiet enim. Fusce est. Vivamus a tellus.
Pellentesque habitant morbi tristique senectus et
Select Country < netus et malesuada fames ac turpis egestas. Proin
pharetra nonummy pede. Mauris et orci. Aenean nec
lorem. In porttitor. Donec laoreet nonummy augue.
Lookup samples Suspendisse dui purus, scelerisque at, vulputate vitae,
pretium mattis, nunc. Mauris eget neque at sem
venenatis eleifend. Ut nonummy. Fusce aliquet pede
non pede. Suspendisse dapibus lorem pellentesque
magna. Integer nulla. Donec blandit feugiat ligula.
Recommended help tools
www.sperotech.com

18. Search / F1 view
Embedded User Assistance
Routine Tools ... Search: Client ID
List of Topics
Client data About Client Data
XYZ > Client > View Sample
About Client Data
Lorem ipsum dolor sit amet, consectetuer adipiscing
Adding a new client elit. Maecenas porttitor congue massa. Fusce posuere,
magna sed pulvinar ultricies, purus lectus malesuada
>
Viewing client samples libero, sit amet commodo magna eros quis urna. Nunc
viverra imperdiet enim. Fusce est. Vivamus a tellus.
Client sample fields Pellentesque habitant morbi tristique senectus et
< netus et malesuada fames ac turpis egestas. Proin
Identifiers pharetra nonummy pede. Mauris et orci. Aenean nec
lorem. In porttitor. Donec laoreet nonummy augue.
Suspendisse dui purus, scelerisque at, vulputate vitae,
pretium mattis, nunc. Mauris eget neque at sem
venenatis eleifend. Ut nonummy. Fusce aliquet pede
non pede. Suspendisse dapibus lorem pellentesque
magna. Integer nulla. Donec blandit feugiat ligula.
Recommended help tools
www.sperotech.com

19. Topic retrieval and display scenario
When the user presses the F1 key in a procedure or routine
The software sends the application context, and requested UA type to
an onboard help subsystem
The help subsystem examines the UA type, knows that a map must be
retrieved and retrieves it
It looks into the map to find out what topic to highlight and sets the
appropriate "selected" attribute
The map gets rendered in a separate step or within a web browser
control (using CSS) e.g. in a TOC pane
The web browser request the topic from the retrieval engine
The topic gets rendered in a topic pane
Related links from within the map are displayed at the end of the topic
www.sperotech.com

20. Alarm help retrieval & display
When an alarm or message is displayed the user can
press on a button or link for more information
The software sends a message identifier, application
context and other metadata to an onboard help subsystem
The help subsystem retrieves the alarm (message)
description topic
Depending on the breadcrumb and other metadata parts
of the description text may be flagged, or filtered out
www.sperotech.com

21. Guided help
When the users clicks on a link like "show me how"
or "show me where"
The help subsystem triggers an event in the software
which brings up the proper screen or dialog
The software regains the input focus and the user can
interact with it
Upon completion the user can navigate back to the help
pane and continue with the help
Notes:
• The help navigation window and software dialog visible at the same time,
otherwise the user will lose track
• Requires tight integration between the help subsystem and the main
software application
www.sperotech.com

22. General troubleshooters
Step Yes No
1. Are the operation ON/OFF switch and circuit breaker 2 3
switched OFF?
2. Switch on both power switches.
3. Is the power cable plug disconnected at either the 4 5
instrument or the outlet?
4. Firmly connect the power cable.
5. Is the main power outlet working? 8 6
6. Check the circuit breaker in the laboratory distribution
box.
7. Ensure line voltage is adequate.
8. If you are still experiencing problems, call technical
support.
www.sperotech.com

23. Yes/No table display option
www.sperotech.com

24. Hardware locaters require textual and
graphical integration, e.g. using SVG
When the users clicks on a link like "show me where"
The appropriate graphic of the instrument is displayed and
the hardware module is displayed
Notes:
• More effective if dynamic images are used (showing how to open a cabinet,
remove a tray, etc.)
• Requires a two-way communication between content developers and
graphic designer in order to link text and graphics.
www.sperotech.com

25. Embedded Help in Silverlight Apps
DITA X
topics A
& Maps M
L
XML
Authoring
and
App designed for
collaboration Transformation using DITA OT UA XAML
www.sperotech.com

26. USING SEMANTIC LAYERS
www.sperotech.com

27. Semantic search and dynamic
reasoning benefits
A semantic layer can help reduce the work for the content development
team
There is less need to create and maintain maps
semantic search can use inference rules to find the right content based on where the user is in
the application or in response to a search request
Search & Find interface more familiar to what people are using everyday on
the Internet
Integration using logical descriptions
The content development team can take responsibility for the whole user
assistance (e.g. field level UA), no dependency on the development team
User experience can be further enriched over time by making more referential
semantics (statements about what is what) available
www.sperotech.com

28. Semantic standards and
technology
Today the open standards for a semantic web are from W3C
RDF – Resource Description Framework
Works with triples to express referential semantics
RDFS – RDF with a Schema
Has more expressive power which allows one to be more precise (e.g.
classes, subclasses and instances of objects)
OWL – Web Ontology Language
Even more expressive power where we can define ranges, domains,
restrictions, etc.
SPARQL – the query language for RDF stores
Besides querying RDF triples, the basis for inference rules and
dynamic reasoning
Issue: Software tools are not widely available or mature yet
www.sperotech.com

29. Conclusions
Embedded help is live, dynamic, interactive, right-on-
spot (in-band)
It provides a better user assistance experience
Help can be made aware of the application state,
user privileges and role
Embedded help makes is feasible to guide untrained
users through the operation of a device or an
application without formal training or having them
consult the documentation
www.sperotech.com

30. www.sperotech.com

31. Thank you
Marc Speyer
Mobile: +31 655 117 459
Email: mspeyer@sperotech.com
Website: www.sperotech.com
Twitter: #sperotech
Leave your business card or send me an email for a white paper
on a new tool to help you create DITA specializations.
www.sperotech.com