Converting from Multiple Formats to DITA-compliant XML
John Kinsky, Intel
Managing a diverse group of writers spread out at many sites. Many documents, converted thousands of pages to DITA-compliant XML, and was able to do the task successfully. Supported multiple OSs, multiple products, and in many cases, multiple languages.
Know what DITA promises. DITA assumes all information can be reduced to bite-size chunks. (When all you have is a hammer, everything looks like a nail.) Minimalism is the order of the day. And DITA might not work for you.
DITA Open Toolkit is a publishing environment, not a magic solution. Requires knowledge of XML, XSL, DTDs.
View from 50,000 ft:
- Analyze current document
- Determine topic types
- Restructure existing, legacy content (better to do in your existing tools; it's faster)
- Convert from legacy format, seciton by section and topic by topic
- Publish document from new sources (concurrent with doing the same with your old sources)
Choose topic types. Concept, task, reference, generic. DITA guys will tell you you can't use the generic topic. But generic topic type solves problems, all other topic types derived from the generic topic type. Use a matrix tracking device (spreadsheet) and assign topic to topic type, plus time value it will take to convert.
Topic type analysis on only part of the overall process. Found a lot of theory, but little practical info for how to deal with conversion. Output dictates the ground rules. Decide before you begin to convert. HTML requires different top-level DITA map structure than PDF. Multiple formats from single source requires additional work and testing.
Choose a path: easy or hard. Easy path, convert everything to concept or generic topic types. Hard path, follow recommendation from nearly everyone else, convert everything to appropriate topic type (which we should). Easy path gets you there quickly, but requires you go back at some time and restructure the content.
Middle path follows the easy path for the bulk of the conversion, follow the hard path for select group of topics.
Use specialization? Sooner or later have to answer the question. Need skillset (XML, XSL, DTDs) for "yes" but "no' restricts your flexibility (but allows you to use out-of-the-box topics.
Have you thought about all possible single-source conditions? Reduced special formatting variations? Decided on image types and sizes? restructured legacy content before conversion? Built a prototype or proof of concept?
Tame the beast. Have one person dedicated to the task. No matter what your conversion estimates are, it's going to take longer. Get help from others who have gone through it. Restructure content in original format before converting. Convert a few to[pics, build, view output. Repeat restructure and convert, over and over.
Voltiare" "The perfect is the enemy of the good." You have to know when good enough is good enough. Keep in mind why you chose to use DITA in the first place.
Developing Product Documentation in a Confluence Wiki
Bruce Michelson, Corda Technologies
Previously outsourced documentation, developed using FrameMaker to PDF and RoboHelp to FlashHelp. Directed to look into wiki.
Goals: collaborative authoring, better and stronger searching, avoid FlashHelp installation, improved documentation. hassle free and low cost production, support for translation.
Considerations: features, search engine and accessibility, export and import tools, backup and version control, security, maintenance and authoring.
Define access; groups; global, space, and page permission.
Developed wiki personas: viewer, contributor, translator, reviewer, publisher, administrator.
Customers, if they have an account, can create or edit pages.
Don't have global search and replace, like when product names change.
Sense of loss of control by writers because anyone can contribute. Lots of fights with developers. Burned bridges by moving source to wiki. Bottleneck with reviewing.