Who’s afraid of the DITA Wolf?

Suchi Govindarajan, MYOB

Presented at AODC 2010http://www.aodc.com.au/overview10.aspx

An origami exercise

Valley, mountain, and crease are the three types of folds from which all origami springs. But even a valley fold is not necessarily the same as another valley fold if the layers of paper do not lie flat. When models move into three dimensions, both valley and mountain folds can vary in another way: the fold angle, which can take on many values.

[Origami Design Secrets, Robert Lang]

What if we’d started with this bit of theory instead?

There are four mathematical rules for producing flat-foldable origami crease patterns:

crease patterns are two colorable at any vertex the number of valley and

mountain folds always differ by two in either direction

Kawasaki's theorem: at any vertex, the sum of all the odd angles adds up to 180 degrees, as do the even.

a sheet can never penetrate a fold.  

Or this?

http://en.wikipedia.org/wiki/Mathematics_of_paper_folding

Theory versus practice

"I actually made something straight away“ No more fear

"I remember doing something like this before“Builds on what you know

"I wonder how it works”Piques your curiosity

"How did they come up with that? How would I make my own designs?”

Path to more learning

Practice is fun for beginners

Barriers to learning DITA

You already know DITA The secret road Doubts? Go further

And now to DITA

Barriers to Learning DITA (Theory & Jargon)

Let’s look at some DITA material

“In this tutorial, you will learn the basic elements in a DITA topic and how they are specialized to become the three core DITA information types: concept task reference"

[http://www.ditausers.org/training/DITATopics/] 

DITA material (continued)

“Darwin because its topics can be specialized to inherit properties of basic topics.

Three basic Information Types are Concept, Task, and Reference topics.

The Architecture is an XML standard, with Schemas and DTDs (document type definitions) maintained by OASIS.

Topics can include other topics and sub-topics for flexible content reuse.

....”[http://www.ditausers.org/about_us/what_is_dita/]

DITA material (contd.)

“Darwin Information Typing Architecture (DITA) is an XML-based, end-to-end architecture for authoring, producing, and delivering readable information as discrete, typed topics.”

 [http://www.oasis-open.org/committees/dita/faq.php]

“A method for organizing and publishing content based on reusable content components.”

 [http://wiki.answers.com/Q/What_is_DITA_for_technical_documentation]

“The Darwin Information Typing Architecture (DITA) is an XML-based method for writing and delivering information in a variety of forms....”

DITA is a standard for technical documents that’s designed to be used with XML. It comes with some free publishing tools. 

A good, jargon-free definition for beginners

http://www.informit.com/articles/article.aspx?p=663081

You already know DITA

DITA Buzzword Pre-DITA usage

Content re-use Content model Single-sourcing Multi-channel

publishing Topic-based authoring Maps

Robohelp FrameMaker and

friends Madcap Flare Tech writing principles

DITA buzzword bingo

Separation of content and form

DITA versus FrameElements

Fixed elements, Fixed order

Attributes

WYSIOO

Related topics are automated

Reuse elements, topics, maps

Maps

Styles

Fixed styles, Order enforced manually

Conditions, Markers

WYSIWYG and WYSIOO

Related topics are manual

Reuse paragraphs, files

Books

The Secret RoadOr “Just Do It"

DITA Users need not install anything1 or know XML to begin topic-based structured

writing today.

The other way to DITA

[http://www.ditausers.org/]

XML editor WYSIWOO view DITA-aware

◦So DITA is just a matter of File> New

◦So DITA rules are embedded

◦So you can look up the DITA specifications in context

Examples: XMLMind, XMetal

The tool for this hike

Theory Elements Attributes The barest idea of Concept, Task, Reference

Tips How to use the ID attribute Quirks of using the ENTER key Using the Insert options

Things you need to know

Specialisation Customisation The DITA “topic" topic Inheritance Relationship tables DTDs XML rules, validation, well-formedness (really?)

Things you don’t need to know

DITA OpenToolkit A closed mind

Wolves on this road

Doubts?

In one hour, nine writers were able to:

◦Write a concept and a task

◦Create a map to pull them together They didn't know what elements were available

◦They discovered them

◦They guessed what they were for The XML Editor used was critical

◦DITA-aware.

◦Used insert options to learn DITA rules

DITA in a day workshop

Elements, attributes DITA being topic-based Authoring mechanics Basic structures

No memory of previous DITA tutorials

Minimalist introduction

Start with a great example Learn simple things first

◦The task/concept/reference decision

◦Notes

◦Cross-references

◦Hyperlinks

◦Tables

My rough guide

Download and analyse sample topics:http://dita‐ot.sourceforge.net/SourceForgeFiles/doc/user_guide.html

Follow the tutorial in DITA for Solo Writers:http://www.ditausers.org/tutorials/lone‐dita/ditaguide.pdf

Sample topics

http://docs.oasis-open.org/dita/v1.1/langspec/ditaref-type.html

Description Example Contains Contained by Inheritance Attributes

Refer to the DITA specification

Go further

WinANT

◦It took 1 hour for the writers in my workshop to install DITA-OT, WinANT and publish to HTML, CHM and PDF

XMLMind DITA Converter Publishing tools you may already own

Publishing

Reinforce your learning Let your requirements guide you Let the possibilities guide you Don’t get taken in by the hype Don’t be cynical about the hype

Iterations of theory and practice

Picture credits:www.flickr.com/photos/jon_tucker/4275210416/

www.flickr.com/photos/shereen84/3187315381/

www.flickr.com/photos/vaguelyartistic/132177047/

www.flickr.com/photos/vaguelyartistic/132177047/

www.origami-fun.com/origami-pelican.html

www.flickr.com/photos/origomi/33173530/

www.flickr.com/photos/origomi/17213276/

www.flickr.com/photos/popupology/4105433338/

www.flickr.com/photos/vaguelyartistic/132177047/

www.flickr.com/photos/oschene/2497103604/

www.flickr.com/photos/bookgrl/482232222/

http://tpettit.best.vwh.net/dolls/pd_scans/52valentine

Title credit: Ron Tierney