How a call for documentation can expand to include many different activities, illustrated with work in progress - presented at Localization World, Paris - TEKOM track, 5 June 2012.

1. C U LT U R E C O M
CULTURE COMMUNICATION TECHNOLOGIE
Ray Gallon

2. The Call:

3. The Product
ž Busi
ness Ac
software tivity Mo
nitoring
(BA M )
— Fits th
e space
Manage between
ment (B Busines
Intelligen PM) and s Proces
c
e (BI). Bus
iness s
two au diences:
lient de scribes
ž C
— IT
t
— Man agemen

4. The Two Audiences
rity of
a l integ
IT:
chnic
ž e d in te g SLA
erest
— Int ess existi
n
pr oc A per
d in Q rnal)
e
erest or exte io n not
— Int a l p plicat e
( intern the a tructur
that fras
n
— C oncer their in
e
d amag
ž Managem
— Interes
e nt:
te
data that d in strategic and
p
rocesses can be e
xtracted f operatio
nal
— Don’t
rom the
have grea
software t desire to
“hands on use the
.”

5. The Discovery Process
ed ne ed:
Exp ress not
ion” – tail
ž entat y de
ocum in an
— “D ware
desc ribed soft
ke the for
: ma tand
ctive ders
— Obje to un
eas ier stom e rs.
p oten tial cu

6. The Discovery Process
ž Inter
views wi
following th key pl
n o n e xp ayers re
ressed n veal the
— A doc eeds:
umentat
— Conte ion ph ilosophy
nt archit
— Help ecture
with a co
audience ntent str
s ategy fo
r the two
— Help
with inte
raction d
esign ch
oices

7. The Discovery Process
ž Inter
views wi
following th key pl
n o n e xp ayers re
ressed n veal the
— A doc eeds:
umentat
ion ph ilosophy
content
— Conte
nt archit
— Help ecture
strategy
with a co
audience ntent str
s ategy fo
r the two
— Help
with inte
raction d
esign ch
oices

8. The Two Audiences: Subtext
INTERACTION
COMMUNICATIONS CHANNEL
I YOU

9. The Two Audiences: Subtext
INTERACTION
COMMUNICATIONS CHANNEL
I SOFTWARE

10. Example: Business Process
Dashboard – Order Fulfillment
User Interaction model: Progressive Disclosure

11. Key Recommendations After
Discovery
ž “Documentation” = Embedded, on line, progressively
disclosed assistance, including decision support
ž Combination of standardized OLH plus customized
material:
— Done by the co. as part of a service contract
— Custom annotations by end user
ž Software must communicate with two voices to the
two audiences
ž Use DITA to maximise reuse, conditional text, etc.
ž No CMS – Use existing configuration management
system for content management, but prepared for
eventual migration

12. two aud iences,
ere are indeed,
ž Th
’t one of them.
b ut IT isn
ž The
real two
— Oper audienc
ational es are:
— Strat people
egy peo
ple

13. In an
Ideal W
ew
p ersonas
ould be before
orl d…
ž Ther
r profiles egins
or use ment b
develop
ž The
se pro
the con files would
tent cr then b
— Inte eation e appli
raction proces ed to
— Interf design s:
ace gr
— Us aphics
er assi
stance
ž Prototypes w ould be tested with real
users or potential users

14. How It Really Happened
ž Product was designed with certain
preconceived notions of user profiles,
never researched
ž Content, tone, etc. not taken into account
at all
ž Real user research considered “too difficult
because there are no users – it’s a new
product”
ž Some of this work now being done, in
parallel with content development

15. Chosen Architecture:
Progressive Disclosure
Link Yes
No
Multiple Links
At Will

16. Adaptation of Process to Reality
hase one:
Pro ject p
Star
t co n
mod tent
e U deve
com A (to lopm
mon ol tip ent o
s, ta
trunk
, use sks, f “stand
r fun etc.) ard”
ction –
s on
ly

17. Adaptation of Process to Reality
ase one: per
in ph p ro
llel, dev elop
In para ers,
al us for
tenti
po oice
rview les dv
Inte rofi
p ton e an
user atin
g
enti ces
iffer dien
Sta rt d t a u
n etter
di ffere ncy, b
nsiste rs
for co t use
Adju st UI , targe
o mi cs
ergon

18. Work in progress

19. Progressive Disclosure
User Interface Click here to
reveal detailed
information

20. Result: a “Portlet”
You can drill down further to see individual transactions
Double click a
line for drill
down

21. User Assistance Progressive
Disclosure Model
Click here for
more help
Enhanced tool
tip is first level
of disclosure

22. User Assistance Progressive
Disclosure Model
Click here for
more help
Enhanced tool
tip is first level
of disclosure
Click here for a
full concept

23. The Concept Pane Opens

24. The Concept Pane Opens
Click here to
open the TOC
Links to more
information at
bottom of
pane

26. Adaptation of Process to Reality
ž Planned Phase Two:
— Find a technical writer to maintain standard
content
— Expand “standard” UA to include
administrative functions
— Adjust UA content and style rules based on
user testing
— Develop input application for SME’s, in-
house consultants
— Develop applet to permit user annotation

27. In Summary:
ž “Help, we need documentation” becomes a
call for:
— Content strategy – voices, user profiling
— UX – user profiling, testing, refining interaction
design, interaction design of UA
— Document Content Architecture – choice of
system, content management strategy
— Information Architecture – structure of the UA
content
— Content development – otherwise known as
writing

28. C U LT U R E C O M
CULTURE COMMUNICATION TECHNOLOGIE
email: infodesign@culturecom.net
Please check out my blog,
« Rant of a Humanist Nerd: »
http://humanistnerd.culturecom.net
Twitter: @raygallon
LinkedIn and Google+: Ray Gallon
Member, board of directors