Jang F.M. Graat
JANG Communication
Amsterdam - Netherlands
DITA for managers
what is the hype really about ?
JANG F.M. Graat
JAN G Communication
Amsterdam - Netherlands
Problems with
documentation
You are not alone...
• IBM produces millions of pages
• Created for modular systems
• Many authors / world-wide departments
• Continuous change...
Problems
• Various authors and departments
• Differences in layout and book composition
• Differences in physical book for...
Problems
• Information in various formats
• Operating manual, service manual, tutorial, training, etc.
• Printing to vario...
Problems
• Cost of translation
• Europe is growing
• CE : Operating manual must be translated
• Translation memories do no...
• One manual covering all product versions
• Not very user-friendly
• Complicated to create and maintain
• No text, only i...
Reuse
• Copy-paste method
• Changes in source: copies are not updated automatically
• Changes in copy: source is not updat...
Reuse
• Various authors and departments
• Differences in styling, layout and composition
• Differences in writing style, c...
Reuse
• Incompatible file formats
Reuse
• Content Management Systems
• The magic formula ?
• Linking to other information systems ?
• Importing and exportin...
Concepts of DITA
Does DITA offer a viable solution ?
What is DITA ?
• Modular documentation strategy
• Minimalism
• Topic-based writing
• Information typing architecture
• Sta...
Modular system
Modular system
Modular system
Modular system
Modular system
Minimalism
• “Less is more”
• No time for big books
• No capacity for learning
• Not interested in background
• Purpose of...
Minimalism
• John M. Carroll (1990)
• IBM documentation team
• Useful information
• When it is needed
• Where it is needed...
Topics
• Answer to a single question
• “How does this work ?”
• “What does that do ?”
• “How do I do this ?”
• “What are m...
Topics
• Advantages
• Efficient for the user
• Recognisable structure
• Immediately reviewable
• Immediately translatable
•...
Topics
Topics Maps Manuals
Information types
• Types of information
• Concept, introduction, background knowledge
• Procedures, tasks, checklists
• R...
Information types
• Classifications since 1960s
• Only 3 types appear in all classifications
• Concept
• “How does this work...
Information types
• Concept
• Explains how something works
• Fairly unrestricted structure
• Paragraphs, figures, lists
• S...
Information types
• Procedure / task
• Safety instructions
• Preconditions
• Step-by-step procedure
• Finishing work
• Ref...
Information types
• Reference / specification
• Identification: where applicable ?
• Full specification
• Lists and tables
• ...
Standard: XML
• XML - eXtensible Markup Language
• Information and meta-information in one file format
• Exchangeable betwe...
Standard: XML
• Markup Language
• Text with meta-information in the same file
• Text plus formating: Word, web pages (HTML)...
Standard: XML
• Organizing information
• All information has a label
• Structure must be valid
<presentation>
<prolog>
<au...
Standard: XML
• Microsoft Word, Excel
• From MS Office 2007
• Adobe FrameMaker
• From version 7.0 (2003)
• Content Manageme...
Standard: XML
• Each program uses only what it needs
• The rest is left untouched
<presentation>
<prolog>
<author>Jang F.M...
Standard: DITA
• XML standard
• Standard XML method of labeling information
• Restriction on the absolute freedom in XML
•...
Standard: DITA
Specialisation
• One size does not fit all
• Made-to-measure is more expensive
• DITA uses “specialisation”
• Adaptations f...
Specialisation
• Custom topic type
• Works as a template
• Order of elements
• New elements
• Less freedom
• Complete info...
Growing fast
Growing fast
• dita.xml.org
• Companies and individual members
• Work on extending and improving the standard
• More and m...
Conclusions
• DITA as a strategy for documentation
• Building documents like you build machines (or software)
• Modularity...
JANG Communication
jang@jang.nlwww.jang.nl
Upcoming SlideShare
Loading in …5
×

DITA for Managers - a non-technical introduction

672 views

Published on

DITA is for technical documentation what CAD is for engineering. Many presentations about DITA go into technical details and do not explain the basic concepts in a language that most managers will be able to relate to. This old (2009) presentation tries to do that and is still very much valid today.

Published in: Business
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
672
On SlideShare
0
From Embeds
0
Number of Embeds
6
Actions
Shares
0
Downloads
16
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

DITA for Managers - a non-technical introduction

  1. 1. Jang F.M. Graat JANG Communication Amsterdam - Netherlands DITA for managers what is the hype really about ?
  2. 2. JANG F.M. Graat JAN G Communication Amsterdam - Netherlands
  3. 3. Problems with documentation You are not alone...
  4. 4. • IBM produces millions of pages • Created for modular systems • Many authors / world-wide departments • Continuous changes to documentation • Publishing to various formats and media • Translation into many target languages Problems
  5. 5. Problems • Various authors and departments • Differences in layout and book composition • Differences in physical book formats • Differences in writing style and idiom
  6. 6. Problems • Information in various formats • Operating manual, service manual, tutorial, training, etc. • Printing to various formats (also color vs. black) • Electronic media: PDF, HTML, CHM,Web 2.0, ...
  7. 7. Problems • Cost of translation • Europe is growing • CE : Operating manual must be translated • Translation memories do not come for free
  8. 8. • One manual covering all product versions • Not very user-friendly • Complicated to create and maintain • No text, only images (e.g. IKEA) • Does not work for most products • Very costly to create and maintain • Reuse of text and illustrations • “Single-source publishing” Solutions ?
  9. 9. Reuse • Copy-paste method • Changes in source: copies are not updated automatically • Changes in copy: source is not updated automatically • No automatic overview of all used copies
  10. 10. Reuse • Various authors and departments • Differences in styling, layout and composition • Differences in writing style, choice of words and structure • Differences in file formats
  11. 11. Reuse • Incompatible file formats
  12. 12. Reuse • Content Management Systems • The magic formula ? • Linking to other information systems ? • Importing and exporting options ?
  13. 13. Concepts of DITA Does DITA offer a viable solution ?
  14. 14. What is DITA ? • Modular documentation strategy • Minimalism • Topic-based writing • Information typing architecture • Standards, no closed system • Specialisations for various areas
  15. 15. Modular system
  16. 16. Modular system
  17. 17. Modular system
  18. 18. Modular system
  19. 19. Modular system
  20. 20. Minimalism • “Less is more” • No time for big books • No capacity for learning • Not interested in background • Purpose of information • What does the user know ? • What must the user do ? • Where is the info required ? • When is the info required ?
  21. 21. Minimalism • John M. Carroll (1990) • IBM documentation team • Useful information • When it is needed • Where it is needed • Easy to find • Quick to take in • Immediately applicable • Short and to-the-point
  22. 22. Topics • Answer to a single question • “How does this work ?” • “What does that do ?” • “How do I do this ?” • “What are my options ?” • “What went wrong ?”
  23. 23. Topics • Advantages • Efficient for the user • Recognisable structure • Immediately reviewable • Immediately translatable • Flexible book composition • Reuse in various publications • Disadvantage • Authors may need to be trained
  24. 24. Topics Topics Maps Manuals
  25. 25. Information types • Types of information • Concept, introduction, background knowledge • Procedures, tasks, checklists • Reference materials, dictionaries • Tables of contents, indexes • Styling and structure • Recognisable for the user • Only one information type per topic • Forces the authors to write consistently
  26. 26. Information types • Classifications since 1960s • Only 3 types appear in all classifications • Concept • “How does this work ?” • Procedure / task • “How do I do this ?” • References / specifications • “What are my options ?”
  27. 27. Information types • Concept • Explains how something works • Fairly unrestricted structure • Paragraphs, figures, lists • Subdivision into sections • References to other information sources • No procedures • No specification of all options • No tables
  28. 28. Information types • Procedure / task • Safety instructions • Preconditions • Step-by-step procedure • Finishing work • References to other information sources • No explanation of how it works • No specification of all options • No tables
  29. 29. Information types • Reference / specification • Identification: where applicable ? • Full specification • Lists and tables • Optional examples • All available options • References to other information sources • No procedures • No explanation of how it works
  30. 30. Standard: XML • XML - eXtensible Markup Language • Information and meta-information in one file format • Exchangeable between all software that understands XML • Extensible without breaking the standard !
  31. 31. Standard: XML • Markup Language • Text with meta-information in the same file • Text plus formating: Word, web pages (HTML), etc. • eXtensible • Define and use your own labels • Information and styling can be detached • Programs are not bothered by unknown labels <title>DITA for Managers</title> <subtitle>What is the hype really about ?</subtitle>
  32. 32. Standard: XML • Organizing information • All information has a label • Structure must be valid <presentation> <prolog> <author>Jang F.M. Graat</author> <company>JANG Communication</company> </prolog> <title>DITA for Managers</title> <subtitle>What is the hype really about ?</subtitle> <section> <title>Problems with documentation</title> <subtitle>You are not alone...</subtitle> ... </section> ... </presentation>
  33. 33. Standard: XML • Microsoft Word, Excel • From MS Office 2007 • Adobe FrameMaker • From version 7.0 (2003) • Content Management Systems • 3D CAD software packages • Version control systems D A T A
  34. 34. Standard: XML • Each program uses only what it needs • The rest is left untouched <presentation> <prolog> <author>Jang F.M. Graat</author> <company>JANG Communication</company> <location>Amsterdam</location> <e-mail>jang@jang.nl</e-mail> </prolog> <title>DITA for Managers</title> <subtitle>What is the hype really about ?</subtitle> <section> <title>Problems with documentation</title> <subtitle>You are not alone...</subtitle> ... </section> ... </presentation>
  35. 35. Standard: DITA • XML standard • Standard XML method of labeling information • Restriction on the absolute freedom in XML • Specifies topics and topicmaps • Contents and structure of DITA documents • Layout is defined by publishing software
  36. 36. Standard: DITA
  37. 37. Specialisation • One size does not fit all • Made-to-measure is more expensive • DITA uses “specialisation” • Adaptations fall within the standard • Made-to-measure without all the disadvantages • Exchangeability is left untouched • Tools can all be used without restrictions
  38. 38. Specialisation • Custom topic type • Works as a template • Order of elements • New elements • Less freedom • Complete information • More conformance • More reusability • Complies to standard
  39. 39. Growing fast
  40. 40. Growing fast • dita.xml.org • Companies and individual members • Work on extending and improving the standard • More and more users • Adobe,Autodesk, ICOS, IBM, Inmedius, McAfee, Nokia, Perspectix, Sybase, Syclo,Teradata,Trackplus, etc. • More and more materials available • Literature, training, workshops about DITA
  41. 41. Conclusions • DITA as a strategy for documentation • Building documents like you build machines (or software) • Modularity, structuredness, flexibility • Information about DITA • Mostly written from within the software industry • Often needlessly complex (techno-babble,‘geekspeak’) • More clear introductions are needed • DITA in practice • Conferences (e.g. DITA Europe 2009 in Munich)
  42. 42. JANG Communication jang@jang.nlwww.jang.nl

×