DITA for Managers - a non-technical introduction
-
Upload
jang-fm-graat -
Category
Business
-
view
213 -
download
1
description
Transcript of DITA for Managers - a non-technical introduction
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>[email protected]</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