quick & dirty introduction to dita

1

Quick & Dirty Introduction to

DITA

2

This presentation is brought to you by someone mildly

attached to DITA

3

Content In the beginning there was a dog & an owner, &

a bone

How Technical User Documentation is Read & Used

A summary of DITA

Why should I use it

How do I use it

4

In the beginning there was a dog & an owner, & a bone

5

Dog, Bone & Owner Scenario

Conversation between dog and dog owner:

The dog owner says: “Nice doggie, don’t bite the postman,

we’ll go for a walk a little later, we could play fetch & then we can go to a café and get you a big doggie bisuit. You have to be a good dog today!”

The dog hears: “Bla...bla....postman...fetch.......walk...biscuit..

good dog Bla...bla....!”

In the beginning there was a dog & an owner & a bone

6

Dog, Bone & Owner Scenarios

Notice the dog’s filtering mechanism?

This is how minimalism works for the listener (in this case, the dog).

There is a need for mininimalism in technical user documentation in order to give the user just what they need, that is, “just-in-time-help”.

In the beginning there was a dog & an owner & a bone

7

Dog, Bone & Owner Scenario

“Let’s go for a walk, & if you’re really , really good, & you don’t bite the post man, we’ll play fetch & I’ll

feed you some really yummy food. You must

behave & be good.

In the beginning there was a dog & an owner & a bone

Bla..bla..bla..Postman...catch...yummy yummy...good! ..bla...bla..

8

How Technical User Documentation is Read & Used

I’m not comparing a reader of technical user assistance materials to dogs but you do see where I’m going with this dog & bone analogy, I hope?

Readers who need to accomplish a task, understand a concept or quickly find a command, or instructions tend to look for the bone and expect to get it quickly. They tend to:

scan documents for signs of possible usefulness, filter for redundancy, trash obsolete or inappropriate information quickly, and focus on the imperatives

bla...bla.. bla.. Oh whoppee I found the installation prerequisites information...

bla...bla.. bla.. Oh whopee, I found

useful comands!!

9

How Technical User Documentation is Read & Used

This is what readers might be looking for:

The big picture

Step-by-step instructions

Reference information

Terms and Defitinions that could be useful

10

How Technical User Documentation is Read & Used

Warning! If your reader does not find what they’re looking for in 15 seconds, they will abandon the reading material.

11

How Technical User Documentation is Read & Used

Which makes the amount of effort invested in preparing, creating, editing & making all that content aesthetically appealing somewhat pointless

12

How Technical User Documentation is Read & Used

Do not despair, instead do this:

Downsize your content into useful chunks of information!

Filter out unnecessary information; avoid information overkill!

Focus on your content & message in each chunk of information (that is, each topic)!

And keep smiling!

DOWNSIZE,FILTER,

FOCUS, SMILE!DOWNSIZE,

FILTER,FOCUS, SMILE!

DOWNSIZE,FILTER,

FOCUS, SMILE

13

How Technical User Documentation is Read & Used

Why should you downsize, filter & focus? Because...

the reader will NEVER read a technical user document in chronological order, from start ot finish, from introduction to appendix.

No one, & I mean no one has really reads from page 1 to 456, except those of us who had the task of proofreading it!

P.S. About those 400+ pages, you skim, you scan, you hope & pray that you’ll find something useful or you abandon hope and approach a colleague for help. When that happens, we’ve failed as technical communicators.

14

How Technical User Documentation is Read & Used

Your user zooms in on the following:

The main thing this piece of beautiful software does is...the big picture, the main concept or idea (conceptual information)

To safely end this taskStep 1. Shut down...Step 2. Remove plug... (procedural or task information)

Keywords, such as troubleshooting, error message number and corresponding messages, or reference lists. (referential information)

CONCEPTUAL, PROCEDURAL and REFERENTIAL information types are represented as topic types in DITA.

15

Coming up next!

In the end there was a dog & an owner & thanks to minimalism in communication and focused delivery of messages the two lived happily ever after.

We´re moving now in the next slides to minimalism & DITA so stop thinking about that dog!

16

A quick & dirty summary of DITA

A quick & dirty summary of DITA

17

b

DITA lends itself well to this concept of minimalism and focus because it’s central theme is TOPICs.

The idea that a minimalistic approach to technical documentation could augment its usage is not new. The idea was flouted in the early 60s, by technically adept geeks but it’s also similar to Chanel’s “less is more” trend (think “little black dress”).

DITA simply makes “less is more” easier to implement in user documentation by centralising the idea of the TOPIC instead of thinking in terms of chapters, manuals and books.

A quick & dirty summary of DITA

18

b

DITA has its historical roots in early 2000

It is the brainchild of IBM’s OASIS group.

DITA enhances the utility of the document for readers by encouraging the writer to think in terms of the smallest unit of information: the topic.

DITA is different to DocBook in this one main respect: it is topic-based & not book-based. DITA is not about chapters, sections, page numbers but about topics.

A topic is a topic is a topic & not a book! Ok, got it?

I won’t reivent the wheel by regurgitating DITA facts. For more details, see http://www.ditareport.com/about_us/history_of_dita/

A quick & dirty summary of DITA

19

b

I won’t bore you, but I do suggest you take a look at some useful of the information available on the web. For example:

http://www.ditainfocenter.com/eclipsehelp/index.jspThis site contains the following:1. DITA Architectural Specification2. DITA Language Specification3. DITA Open Toolkit User Guide4. DITA Architectural Specification v1.15. DITA Language Specification v1.1

That’s my favourite reference guide but just use googlesearch to come up with more information.

A quick & dirty summary of DITA

20

Why should I use it?

21

So that…

users can find relevant information quickly & use it effectively

to improve the way you write, store & use product information.

to make it easy to update and maintain your information.

22

How do I use it?

23

By transforming the DITA XML files into format that are more specifically suitable as user documentation. For example you can transform your DITA XML files uisng the DITA OT Toolkit into

HTML

PDF

Eclipse Helps

CHM

Transformation isn‘t easy so instead of tweaking the toolkit yourself, simply use the sopera-dita framework.

24

Before you get to the transformation stage,

1.simply check out:

https://code.google.com/p/sopera-dita-framework/source/browse/#svn/trunk

2. Create a ditamap and topics

3. Use the convert.jar in the checked out sopera-dita framework folder. For instructions, see

1. http://code.google.com/p/sopera-dita-framework/wiki/UsingThisFramework

&

2. http://code.google.com/p/sopera-dita-framework/wiki/README