DITA for Managers - a non-technical introduction
•
1 j'aime•1,219 vues
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.
Recommandé
Contenu connexe
Plus de Jang F.M. Graat
Plus de Jang F.M. Graat (20)
Dernier
Dernier (20)
DITA for Managers - a non-technical introduction
- 1. Jang F.M. Graat JANG Communication Amsterdam - Netherlands DITA for managers what is the hype really about ?
- 2. JANG F.M. Graat JAN G Communication Amsterdam - Netherlands
- 3. Problems with documentation You are not alone...
- 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. Problems • Various authors and departments • Differences in layout and book composition • Differences in physical book formats • Differences in writing style and idiom
- 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. Problems • Cost of translation • Europe is growing • CE : Operating manual must be translated • Translation memories do not come for free
- 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. 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. 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. Reuse • Incompatible file formats
- 12. Reuse • Content Management Systems • The magic formula ? • Linking to other information systems ? • Importing and exporting options ?
- 13. Concepts of DITA Does DITA offer a viable solution ?
- 14. What is DITA ? • Modular documentation strategy • Minimalism • Topic-based writing • Information typing architecture • Standards, no closed system • Specialisations for various areas
- 15. Modular system
- 16. Modular system
- 17. Modular system
- 18. Modular system
- 19. Modular system
- 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. 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. 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. 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
- 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. Standard: DITA
- 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. 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. Growing fast
- 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. 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)