Introduction to DITA

Editor's Notes

• #2: Thank you for coming tonight and giving us the opportunity to speak. We know that many of you are very curious about DITA and we hope this talk gives you a good sense of its features and the business case for using it. We’ve spoken with some of you individually about the power of DITA, and I gave a lightning talk about DITA at a writethedocs meetup over the summer. From there, Mike Jang asked me if I wanted to expand the talk to include a more detailed introduction to DITA. So Leona and I have teamed up to do that. How many of you have used DITA? We’re going to walk you through the problems of documentation and how DITA solves them, as well as walk you through an example from the toolkit. We’re hoping that by the end of this talk, you’ll know whether DITA might be a good choice for your shop. We’ll have Q&A at the end, please hold your questions until then.
• #3: WE ARE: Melanie: 4 years at Jive, 15 years as a tech writer Came to DITA not by choice, Jive was already using it when I was hired extensive conditional text/filtering exp with FrameMaker Now a true DITA believer! Leona has been Tech Writing for 17 years and using DITA for almost 5. DITA and social collaboration has streamlined the way she works. She looks forward to the evolution of it all. Hit us up on email or Twitter, or call us at Jive.
• #4: MELANIE: DITA = Darwin Information Typing Architecture Originally developed by IBM, but now an international open source standard for creating and delivering documentation. OASIS is the governing body for DITA, just like w3 is for the html standard. Why use DITA and not something else? For that we first need to think about and define the challenges we face as documentarians.
• #5: MELANIE: Writing and delivering docs can be very inefficient: Formatting – some tech writers still spend a lot of time futzing with formatting. That takes a lot of time. Time is money. Product variations – you have the same product built for Linux, Windows, or Apple. Many shops still maintain and update content for all of these publications even though they share a large portion of the same material. Takes a lot of time. Time is money. Translating – translating all of those takes a lot of money. With DITA: Formatting – help topics are written in XML, which removes content from formatting. Writing in xml, you no longer worry about formatting. This saves time and money. XML forces certain structures for authoring, but DITA is flexible; you can design your own structures as well. Product variations – with powerful filtering/conditional text features, DITA allows you to write content once but publish in many combinations and outputs. Conditional text can be applied at the topic, paragraph, phrase, and word level. Imagine publishing twenty different publications from one source of content. For example, at Jive, we publish several different outputs from the same source. You can check those out on our website, docs.jivesoftware.com, and Leona will be showing some specific examples later. Translation – you translate once and deliver it to a lot of different places/publications. No more translating each manual for the Linux, Windows, Mac, and so on versions. Context-sensitive in-product help -- XML can easily be part of your software product's actual code base, making context-sensitive Help easy to deliver. Maintenance and scale -- all of the previous items make maintenance that much easier. DITA solves problems of scale. Bottom line is the bottom line: save time and money. Do more with less. Publish and maintain 1500 topics with just three writers.
• #6: LEONA: DITA addresses major build and automation challenges by: Providing much automation and specialization OOTB Being flexible enough to integrate with so many CMS’s or file repositories Making it possible to keep costs down Initial and Maintenance Costs XML editors are relatively cheap and DITA-OT is Open Source. Relatively Simple to Get Started A few basic resources can get you started. You can leverage an international user and support base by asking questions in Use forums for help (see resources). We’ll show you an example in a few minutes. DITA user group and reaching out in your own community (like the PDX DITA User Group!) Automation DITA can be automated using most tools: Oxygen, CMS, ant, jenkins, or any other tool. You can use what you’re familiar with. You may start Oxygen (as we’ll show in a bit), but as your content set grows, you may need to automate your builds in a tool like jenkins or in a CMS. Specializations available for more focused output You can add different specializations to your toolkit. For example, Training specialization, machine industry, etc.
• #7: LEONA: DITA Produces output that's customized and pretty, yet in formats to please the masses. Deployment Obstacles DITA provides many output options, like PDF, Eclipse, HTML, e-book, etc from one source. For example here at Jive, we publish Jive for Mobile to four formats: html: http://docs.jivesoftware.com/cloud_int/end_user/jive.help.mobile/#user/UsingJiveforiOSApp.html pdf: http://docs.jivesoftware.com/jive/7.0/community_user/topic/jive.help.mobile/pdf/UsingJiveforiOSApp.pdf Eclipse Help Center: http://docs.jivesoftware.com/jive/7.0/community_user/index.jsp native mobile browser: http://docs.jivesoftware.com/mobile_format/jive_iOS/index.html Customizable Look & Feel in Output You can customize by modifying CSS, XSLT/fo, etc in one place for all sources/books.
• #8: MELANIE: switch over to Oxygen and show map manager of hierarchy sample from the toolkit Download the OT or get Oxygen Content is created as a type: topic, task, concept, or reference. Because XML enforces structure, each of these has specific elements in a specific order. But please do not let that put you off. It’s also very versatile. Here’s are some examples of content and how it looks in both Author and Text modes. Here’s how the topics are structured in the maps manager. Filtering: see my blog post Understanding Filtering (http://pdxdita.ditamap.com/?p=159) and Getting Started with Filtering (http://pdxdita.ditamap.com/?p=192) on pdxdita.ditamap.com. LEONA: Here’s how you would build it Here’s the final output
• #9: MELANIE Do a content audit. What will be the growth of your content set over time?
• #10: LEONA Oxy provides great support if you purchase their tool, or purchase their WebHelp plugin.
• #11: Questions?