www.sperotech.com

Embedded User Assistance

NLDITA 2011

By Marc Speyer

www.sperotech.com

Agenda

Sperotech background

Traditional versus embedded help

Using DITA for embedded help

Implementation scenarios

Using Semantic layers

www.sperotech.com

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

TRADITIONAL HELP VERSUS

EMBEDDED

www.sperotech.com

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

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

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

Onboard versus offboard

onboard, integrated

and immediate

How do I?

What is this?

What should I enter?

Which should I select?

What is next?

offboard, standalone

What is this all about?

Why do I need to do

this?

How can I experiment?

I have no time and need help now I have more time to read the help

www.sperotech.com

Process User Assistance

Styles Rules

Topics

Maps

Metadata Interaction

Onboard

Online

Offline

Create

Taxonomy / subject scheme

Controlled vocabulary (sw locators)

Structured authoring tools

Authoring guidelines

Validation & preview tools

CSS style properties

XSLT /XSL-FO files

Build scripts

Open Source tools

Rendering software (PDF)

UA integration subsystem

Interactive dynamic help

Traditional on-line help

e-books (PDF, ePub)

e-learning

Content Development HID Software Dev. Production

User Assistance Process View

www.sperotech.com

UA Stakeholders

Be sure to include all stakeholders

UA

Requirements

Process Customers (funders)

Users

Requirements analysts

Software Developers

Testers

Content developers

Project managers Legal staff

Manufacturing

Sales & Marketing

Field support

Help desk

www.sperotech.com

USER ASSISTANCE USING

DITA

www.sperotech.com

DITA topics and specializations

UA Specializations (technical content, guided help)

Base (technical content)

Root (not used)

Topic

Concept Task

Trouble-shooter

Reference

Locator AlarmDesc Tasklist FAQ

GlossEntry

DITA Topics and specializations

www.sperotech.com

Maps and reuse of task-maps

Online help

Introduction

topic

topic

…

How to perform a test rerun on the

test panel

How to's

Task1

Task2

Task3

Software reference

Start conditions

QA parameters

www.sperotech.com

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

IMPLEMENTATION

SCENARIOS

www.sperotech.com

Field Validation Embedded User Assistance

Date

...ToolsRoutine

Your name

Your address

Postal code

How to enter a valid id →

Enter a valid ID

Select Country

Serum Normal

31-5-2011

31-5-2011

Dr. A. Utziniker

30-05-2010

05-04-2010

23-02-2010

Search term

ID:

Name:

Address:

Zip:

Client Data

>

<

Client Sample

Sample ID: 17661

Sample type: Priority:

Order date: ...

Collection date: ...

Therapist

Name: Change..

Tests:Lookup samples

Search:

www.sperotech.com

Embedded Help Topic Embedded User Assistance

...ToolsRoutine

Your name

Your address

Postal code

Select Country

Search term

ID:

Name:

Address:

Zip:

Client Data

>

<

About Client Data

Lookup samples

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna. Nunc viverra imperdiet enim. Fusce est. Vivamus a tellus. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin 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

XYZ > Client > View Sample

Search:

www.sperotech.com

Search / F1 view Embedded User Assistance

...ToolsRoutine Client ID

Identifiers

Adding a new client

Client data

Viewing client samples

About Client Data

Client sample fields

>

<

About Client Data

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna. Nunc viverra imperdiet enim. Fusce est. Vivamus a tellus. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin 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

XYZ > Client > View Sample

Search:

List of Topics

www.sperotech.com

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

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

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

General troubleshooters

Step Yes No

1. Are the operation ON/OFF switch and circuit breaker

switched OFF?

2 3

2. Switch on both power switches.

3. Is the power cable plug disconnected at either the

instrument or the outlet?

4 5

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

Yes/No table display option

www.sperotech.com

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

Embedded Help in Silverlight Apps

X A M L

App designed for UA XAML

DITA topics

& Maps

Transformation using DITA OT

XML Authoring

and collaboration

www.sperotech.com

USING SEMANTIC LAYERS

www.sperotech.com

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

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

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

www.sperotech.com

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.