Quick dirty introduction to dita
Download
1 / 24

Quick & Dirty Introduction to DITA - PowerPoint PPT Presentation


  • 230 Views
  • Uploaded on

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.

loader
I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
capcha
Download Presentation

PowerPoint Slideshow about ' Quick & Dirty Introduction to DITA' - delano


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


Content
Content attached to DITA

  • 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



Dog bone owner scenario

In the beginning there was a dog & an owner & a bone attached to DITA

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 attached to DITA

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 attached to DITA

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 attached to DITA

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 attached to DITA

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 attached to DITA

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 attached to DITA

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 attached to DITA

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 attached to DITA

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 attached to DITA

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! attached to DITA

  • 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 attached to DITA

A quick & dirty summary of DITA


A quick & dirty summary of DITA attached to 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.


A quick & dirty summary of DITA attached to 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?


A quick & dirty summary of DITA attached to 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? attached to DITA


So that… attached to DITA

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


Before you get to the transformation stage, more specifically suitable as user documentation. For example you can transform your DITA XML files uisng the DITA OT Toolkit into

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


ad