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

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

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

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

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

18. 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?

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

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 • http://code.google.com/p/sopera-dita-framework/wiki/UsingThisFramework & • http://code.google.com/p/sopera-dita-framework/wiki/README