Your SlideShare is downloading. ×
Embedded User Assistance Using DITA
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Embedded User Assistance Using DITA

1,205
views

Published on

Presentation at STC Technical Communication Summit, 2013 - #stc13. This presentation explores how to embed concepts in DITA task topics without breaking the DITA semantic structure. Includes theory …

Presentation at STC Technical Communication Summit, 2013 - #stc13. This presentation explores how to embed concepts in DITA task topics without breaking the DITA semantic structure. Includes theory and practical elements drawn from real current projects.

Published in: Technology, Education

0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,205
On Slideshare
0
From Embeds
0
Number of Embeds
5
Actions
Shares
0
Downloads
31
Comments
0
Likes
3
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. RAY  GALLONC U L T U R E C O MPresentation  ©  2012  Ray  Gallon  all  rights  reservedEmbedding User Assistancewith DITAMember, Board of DirectorsWednesday, 8 May 2013
  • 2. Presentation  ©  2012  Ray  Gallon  all  rights  reservedResearch  collaborator  and  principal,  The  Transformation  Society,  a  new  research  and  training  institute  in  Barcelona,  Spain20  years  in  technical  communication  with  major  companies  such  as  G.E.  Healthcare,  Alcatel,  IBM,  etc.Member,  board  of  directors,  Society  for  Technical  Communication  (STC)Past  president,  STC  FranceAward-­‐winning  radio  producer  and  journalist  –  CBC,  NPR,  France  Culture,  etc.  and  former  programme  manager,  WNYC-­‐FM,  New  York  Public  RadioAbout MeOwner/Consultant, Culturecom – specialist in usability,content strategy, and user assistance for softwareThe Humanist NerdWednesday, 8 May 2013
  • 3. Presentation  ©  2012-­‐2013  Ray  Gallon  all  rights  reservedBefore Proceeding, DecideModern  software’s  complexity,  features,  &  power  can  leave  users  perplexed  –  often  just  when  they  have  some  immediate,  contingent  need:  “I  need  to  get  this  done,  and  NOW!.”Wednesday, 8 May 2013
  • 4. Presentation  ©  2012  Ray  Gallon  all  rights  reservedBefore Proceeding, DecideUser  assistance  that  is  limited  to  procedures  cannot  help  people  with  contingent  needs.  They  need  to  decide  which,  if  any,  procedures  they  need  to  use.  Long  conceptual  topics  might  provide  insight.But  people  with  contingent  needs  are  not  going  to  wade  through  long  texts.We  can  help  users  get  real  work  done  more  quickly  with  a  bit  of  decision  support.Wednesday, 8 May 2013
  • 5. Presentation  ©  2012  Ray  Gallon  all  rights  reservedDecision Support for UsersTwo  types  of  decision  support  in  software:Automated  decision  support  aidsInformation  designed  to  inform  the  users  judgment,  but  not  formalized  into  an  automated  systemIn technical communication, most of the timewe do the latter type.Wednesday, 8 May 2013
  • 6. Presentation  ©  2012  Ray  Gallon  all  rights  reservedCore Principles forDecision Support of AnyTypeBegin  with  users’  needsGive  priority  to  process  over  productsLink  information  between  producers  and  usersBuild  connections  across  disciplines  and  organizationsSeek  institutional  stabilityDesign  processes  for  learningSource:  U.S.  National  Research  CouncilWednesday, 8 May 2013
  • 7. Presentation  ©  2012  Ray  Gallon  all  rights  reservedCore Principles of Minimalism asRestated by JoAnn HackosFocus  on  an  action-­‐oriented  approach(Users’  needs,    process)Ensure  you  understand  the  users’  world(Users’  needs,  links  and  connections,  institutional  stability)  Recognize  the  importance  of  troubleshooting  information  (Users’  needs,  links  and  connections,  learning)Ensure  that  users  can  find  the  information  they  need  (Users’  needs,  learning,  links  and  connections)Source:  http://www.infomanagementcenter.com/Resources/eNews2012-­‐12JHackos.pdfWednesday, 8 May 2013
  • 8. Presentation  ©  2012  Ray  Gallon  all  rights  reservedIs memorizing a procedure by rote necessaryfor competency?STEP  1STEP  2STEP  3DO  THISDON’T  DO  THATNOTE:WARNING!Is  it  “minimal”  if  users  need  to  go  back  to  the  help  repeatedly?How  does  a  user  know  if  s/he  even  wants  or  needs  to  do  this  task?Doesn’t  it  stand  to  reason  that  when  “learning  by  doing,”  we  include  the  concepts  that  help  the  user  generalize  to  similar  tasks?John  Carroll,  who  created  minimalism,  said:People  using  products  are  most  interested  in  getting  real  work  done.  People  best  learn  about  product  use  by  doing  something  rather  than  reading  about  something.  Wednesday, 8 May 2013
  • 9. Presentation  ©  2012  Ray  Gallon  all  rights  reservedNot Just Minimal – Minimal and MeaningfulPeople  best  learn  about  product  use  by  doing  something  and  making  connections  in  the  process.  Learn  by  doing  –  put  the  concepts  where  they  will  be  useful  and  remembered.It’s  minimal  and  meaningful  if  one  look  at  one  task  helps  us  understand  many  related  tasks.It’s  minimal  and  meaningful  if  one  quick  look  tells  us  we  don’t  need  to  bother  with  this  (or  that  we  do).Wednesday, 8 May 2013
  • 10. Presentation  ©  2012  Ray  Gallon  all  rights  reservedThe Solution: Double EmbeddednessEmbedproceduralUserAssistancedirectlyintotheInterface Embed simpleconcepts directlyinto theUser AssistanceWednesday, 8 May 2013
  • 11. Presentation  ©  2012  Ray  Gallon  all  rights  reservedEmbedded User Assistancefor Noz Urbina’s Mother5  year  problem:  GONE!Informa5on  Architecture:  Not  hidden  but  out  of  the  way  when  not  neededContent  Strategy  &  Technical  Wri5ng:  Simplicity,  voice,  tone,  Task  structure,  delivery  formatBusiness  Analysis  solves  a  long-­‐standing  problem  using  content  tools/methodologiesWednesday, 8 May 2013
  • 12. Presentation  ©  2012  Ray  Gallon  all  rights  reservedEmbedded User Assistancefor Noz Urbina’s Mother5  year  problem:  GONE!Informa5on  Architecture:  Not  hidden  but  out  of  the  way  when  not  neededContent  Strategy  &  Technical  Wri5ng:  Simplicity,  voice,  tone,  Task  structure,  delivery  formatBusiness  Analysis  solves  a  long-­‐standing  problem  using  content  tools/methodologiesOBVIOUSLY,  SHE  COULD  HAVE  READ  THE  MANUAL–  BUT  WOULD  SHE  HAVE?WOULD  SHE  REMEMBER  NEXT  TIME?Wednesday, 8 May 2013
  • 13. Presentation  ©  2012  Ray  Gallon  all  rights  reservedKanban Information:Help Users LearnYour Software FastWe  want  to  give  the  user  all  the  information  s/he  needs  and  only  the  information  s/he  needs.We  want  to  deliver  that  information  when  s/he  needs  it  –  which  implies,  at  the  moment  s/he  has  real  work  to  do.The  logical  conclusion  is  that  user  assistance  needs  to  be  embedded  in  the  software  itself,  in  such  a  way  that:The  user  can  find  it  immediately,  without  excessive  searching,  if  s/he  needs  it.If  s/he  doesn’t  need  it,  it  stays  out  of  the  way.Wednesday, 8 May 2013
  • 14. Presentation  ©  2012  Ray  Gallon  all  rights  reservedKanban Information:Help Users LearnYour Software FastFor  the  most  part,  we’ve  assumed  that  means  procedures.  Concepts  are  out  -­‐  too  long,  too  messy,  too  irrelevant.  The  user  wants  to  meet  her  or  his  contingent  need.Some  users  will  infer  underlying  principles  and  concepts  from  repeated  procedures.  Others,  however,  will  not,  unless  we  point  them  to  it  in  some  way.We  want  the  user  to  understand  the  information  in  a  way  that  s/he  can  apply  it  to  other  situations,  without  needing  to  call  repeatedly  on  the  user  assistance.Wednesday, 8 May 2013
  • 15. ...AND  WHEN????Presentation  ©  2012  Ray  Gallon  all  rights  reservedIntegrated Competency LearningAdapted  by  Dr.  Neus  Lorenzo  from  Phil  Ball  &  Keith  Kelly  (2009)    Ref:  http://ow.ly/dLK8g    &    http://goo.gl/Ul3A2+  Individually  significantcontextualisation  (contingency)+Socio-­‐cultural  construction(information    sharing,  mentoring)+Procedural  Memorisation+  Cognitive  construction  and  process  reasoning+Code:  Mastery  of  the  language,  interface,  iconography...+Thematic  knowledge(SME)User  Learning  SpaceWHERE  IN  THIS  SPACE  DO  YOU  WANT  YOUR  USERS?Wednesday, 8 May 2013
  • 16. Presentation  ©  2012  Ray  Gallon  all  rights  reservedDouble Embeddedness usingProgressive Information DisclosurePeople  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  DisclosureSource:  http://www.nngroup.com/articles/progressive-­‐disclosure/Wednesday, 8 May 2013
  • 17. Presentation  ©  2012  Ray  Gallon  all  rights  reservedDEMOWednesday, 8 May 2013
  • 18. !Presentation  ©  2012  Ray  Gallon  all  rights  reservedEnhancedToolTip:a DITA GenericTopicThe  <shortdesc>  is  what  pops  up  on  hover  (Level  1)The  topic  body  and  link  are  shown  in  the  tool  tip  slideout  (Level  2)The  <abbreviated-­‐form>  glossary  entry  is  resolved  without  popup  definition  in  the  tool  tip.  It  is  rendered  differently  in  the  task  topic.  This  is  managed  from  the  CSSThe  <resourceid>  element  links  the  tool  tip  to  the  interface  element.  ID’s  managed  by  the  development  team  with  tech  comm  input.Wednesday, 8 May 2013
  • 19. !Presentation  ©  2012  Ray  Gallon  all  rights  reservedProcess QueryTaskTopicThis  time  the  abbreviated-­‐form  is  resolved  on  hover……to  pop  up  a  <keyref>  that  points  to  a  glossary  entryThe  <shortdesc>  and  first  <p>  are  reused  from  the  tool  tipWednesday, 8 May 2013
  • 20. Presentation  ©  2012  Ray  Gallon  all  rights  reservedBlending Concepts andTasks:Kanban Information meets DITA• We  often  use  concepts  to  introduce  &  lead  into  multiple  tasks:Concept:   This   concept  explains   what   this   element  of  the  interface  is  all  about.  It  is  used  in  the  following  tasks:Task  1 Task  2 Task  3 Task  4• We  dont  know  how  else  to  do  it,  but  this  is  an  inappropriate  use  of  conceptual  information:• Not  good  cognitive  development• Not  good  KanbanWednesday, 8 May 2013
  • 21. Presentation  ©  2012  Ray  Gallon  all  rights  reservedBlending Concepts andTasks:Kanban Information meets DITAWhy  not  use  the  DITA  Task  topic  structure  to  deliver  conceptual  information  where  it  will  do  the  most  good  and  be  best  remembered?!Wednesday, 8 May 2013
  • 22. !Presentation  ©  2012  Ray  Gallon  all  rights  reservedExample<shortdesc>  (from  tool  tip)<context>The  first  <p>  comes  from  tool  tipWednesday, 8 May 2013
  • 23. Presentation  ©  2012  Ray  Gallon  all  rights  reservedUse <choice> lists and <info> toinclude conceptual information<cmd><choices><info>Wednesday, 8 May 2013
  • 24. Presentation  ©  2012  Ray  Gallon  all  rights  reserved<choicetable> offers another option<cmd><choicetable>Wednesday, 8 May 2013
  • 25. Presentation  ©  2012  Ray  Gallon  all  rights  reserved<stepresult> used in <step> andnested <substep><substeps><substep>            <stepresult><step>            <stepresult>All  these  elements  are  available  after  a  <cmd>.  Use  the  one  that  works  best,  semantically.Wednesday, 8 May 2013
  • 26. Presentation  ©  2012  Ray  Gallon  all  rights  reservedAnother ApproachThanks to Nathalie Laroche and IxiasoftTool  Tip  Level  1Wednesday, 8 May 2013
  • 27. Presentation  ©  2012  Ray  Gallon  all  rights  reservedAnother ApproachThanks to Nathalie Laroche and IxiasoftTool  Tip  Level  2Wednesday, 8 May 2013
  • 28. Presentation  ©  2012  Ray  Gallon  all  rights  reservedAnother ApproachThanks to Nathalie Laroche and IxiasoftTool  Tip  Level  1Tool  Tip  Level  2Wednesday, 8 May 2013
  • 29. Presentation  ©  2012  Ray  Gallon  all  rights  reservedAnother ApproachThanks to Nathalie Laroche and IxiasoftWednesday, 8 May 2013
  • 30. Presentation  ©  2012  Ray  Gallon  all  rights  reservedDITA CompositeTopic –One Size Fits AllThe  composite  topic  begins,  simply,  with  a  <dita>  tag.  You  can  then  insert  any  type  of  DITA  topic,  nested  within  it,  including  <reference>  (not  shown).Use  with  great  caution!Wednesday, 8 May 2013
  • 31. Presentation  ©  2012  Ray  Gallon  all  rights  reservedRAY  GALLONC U L T U R E C O MEmail:   infodesign@culturecom.netThank  You!Google  Plus:  +Ray  GallonTwitter:  @RayGallonLinkedIn:  Ray  GallonVisit  my  blog,  Rant  of  a  Humanist  Nerd:http://humanistnerd.culturecom.netPortions  of  this  presentation  based  on  research  by  the  Transformation  Society  Research  group.Member, Board of DirectorsWednesday, 8 May 2013

×