Quick dirty introduction to dita
This presentation is the property of its rightful owner.
Sponsored Links
1 / 24

Quick & Dirty Introduction to DITA PowerPoint PPT Presentation


  • 138 Views
  • Uploaded on
  • Presentation posted in: General

Quick & Dirty Introduction to DITA. This presentation is brought to you by someone mildly attached to DITA. 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.

Download Presentation

Quick & Dirty Introduction to DITA

An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.


- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -

Presentation Transcript


Quick dirty introduction to dita

Quick & Dirty Introduction to DITA


This presentation is brought to you by someone mildly attached to dita

This presentation is brought to you by someone mildly attached to DITA


Content

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


In the beginning there was a dog an owner a bone

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


Dog bone owner scenario

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

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....!” 


Dog bone owner scenarios

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

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


Dog bone owner scenario1

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

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.

Bla..bla..bla..

Postman...catch...yummy yummy...good! ..bla...bla..


How technical user documentation is read used

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!!


How technical user documentation is read used1

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


How technical user documentation is read used2

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.


How technical user documentation is read used3

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


How technical user documentation is read used4

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


How technical user documentation is read used5

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.


How technical user documentation is read used6

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 task

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


Coming up next

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!


A quick dirty summary of dita

A quick & dirty summary of DITA

A quick & dirty summary of DITA


Quick dirty introduction to dita

A quick & dirty summary of DITA

A summary of DITA

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.


Quick dirty introduction to dita

A quick & dirty summary of DITA

A summary of DITA

b

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

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


Quick dirty introduction to dita

A quick & dirty summary of DITA

A summary of DITA

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

This site contains the following:

  • DITA Architectural Specification

  • DITA Language Specification

  • DITA Open Toolkit User Guide

  • DITA Architectural Specification v1.1

  • DITA Language Specification v1.1

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


Why should i use it

Why should I use it?


Quick dirty introduction to dita

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.


How do i use it

How do I use it?


Quick dirty introduction to dita

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.


Quick dirty introduction to dita

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

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

    &

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


  • Login