DITA for managers. what is the hype really about? Jang F.M. Graat. JANG Communication Amsterdam - Netherlands

Transcription

1 DITA for managers what is the hype really about? Jang F.M. Graat JANG Communication Amsterdam - Netherlands

2 JANG F.M. Graat JANG Communication Amsterdam - Netherlands

3 Problems with documentation You are not alone...

4 Problems 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

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 Solutions? 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

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

24 Topics Topics Maps Manuals

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 D A T A 3D CAD software packages Version control systems

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> </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)

42 JANG Communication