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)



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



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.



Before Proceeding, Decide

Modern software: complex, powerful, perplexing

but

“I need to get this done, and NOW!.”



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?



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



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

http://www.peopleandplace.net/on_the_wire/2011/3/21/principles_for_effective_decision_support__national_research_council%2520read%252025%2520july%25202011

http://www.peopleandplace.net/on_the_wire/2011/3/21/principles_for_effective_decision_support__national_research_council



The Solution: Double Embeddedness

Embed procedural User Assistance

directly into the Interface

Embed simple concepts directly into the User Assistance



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



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?



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.



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/

http://www.nngroup.com/articles/progressive-disclosure/





Example: Business Process Dashboard – Order Fulfillment

User Interaction model: Progressive Disclosure



Discovery Process

Expressed needs:

“Documentation” – not described in detail

Objective: make the software easier to

understand for potential customers.



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



The Big Surprise

The real two audiences are: Operational people Strategy people

!There are indeed, two audiences, but

IT isn’t one of them.



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



▪ 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



Chosen Tools

DITA No CMS -‐ Use existing SVN but

prepared for future expansion

Editor: oXygen

Output: JavaHelp (sorry)



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



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



DEMO



!

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)



!

Process Query Task Topic

<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



<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



!

Example

<context> First <p> comes

from tool tip

<shortdesc> (from tool tip)



Use <choice> lists and <info> to include conceptual information

<cmd>

<choices>

<info>



<choicetable> offers another option

<cmd>

<choicetable>



<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.



Another Approach Thanks to Nathalie Laroche and Ixiasoft

Tool Tip Level 1



Tool Tip Level 2





Tool Tip Level 2

Tool Tip Level 1






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



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

Technology

Low-Cost Embedded UA Using DITA