Jang F.M. GraatJANG CommunicationAmsterdam - Netherlands

DITA for managerswhat is the hype really about ?

JANG F.M. Graat

JANG Communicat ionAmsterdam - Netherlands

Problems with documentation

You are not alone...

• 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

Problems

• Various authors and departments• Differences in layout and book composition

• Differences in physical book formats

• Differences in writing style and idiom

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, ...

Problems

• Cost of translation• Europe is growing

• CE : Operating manual must be translated

• Translation memories do not come for free

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

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

Reuse• Various authors and departments

• Differences in styling, layout and composition

• Differences in writing style, choice of words and structure

• Differences in file formats

Reuse

• Incompatible file formats

Reuse

• Content Management Systems• The magic formula ?

• Linking to other information systems ?

• Importing and exporting options ?

Concepts of DITADoes DITA offer a viable solution ?

What is DITA ?

• Modular documentation strategy

• Minimalism

• Topic-based writing

• Information typing architecture

• Standards, no closed system

• Specialisations for various areas

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 information• What does the user know ?

• What must the user do ?

• Where is the info required ?

• When is the info required ?

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

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

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

Topics

Topics Maps Manuals

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

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

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

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

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

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 !

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>

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>

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

DATA

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>

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

Standard: DITA

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

Specialisation

• Custom topic type• Works as a template

• Order of elements

• New elements

• Less freedom

• Complete information

• More conformance

• More reusability

• Complies to standard

Growing fast

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

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)

JANG Communication

jang@jang.nlwww.jang.nl