Bernard Aschwanden, founder and President of Publishing Smarter provided an informative and entertaining presentation on the lifecycle of a DITA project from planning through production and publishing to various formats. This meeting drew a good number of people "in-house" as well as many remote visitors from around the country, and one person from Malaysia.
Bernard starts off by scoping and planning the project with a spreadsheet (see Estimates.xlsx) which lists the topic type, file name, title, short description and other properties of each file to be created. This not only helps in the planning process but with a little setup (and programming) you can use this information to generate the map and stubs for all topics and a prototype of the documentation deliverable in whatever formats are needed. This initial prototype can be used as the first draft of the document to be signed off by all those involved. You can use the spreadsheet to track progress (or the lack thereof) throughout the project.
Bernard demonstrated that with DITA, "content is king," and the tools used for authoring and publishing aren't as important as they were before XML authoring. He worked with the files in his sample project in a number of editors, and outlined the strengths and weaknesses of each tool (oXygen, XMetaL, FrameMaker, and Serna Free). Because your content lives in XML, you're free to mix and match editors as needed for your workflow. Different authors may have different needs, and DITA can accommodate that quite nicely as long as you're working with a DITA-compliant editor. He then imported the content into a CMS (easyDITA), to show the potential benefits of a browser-based editor.
Be sure to check out Bernard's website, in particular the resources area ..
We had a very lively and energetic discussion of various topics. I've organized them into three main groups below.
TOPIC 1: Converting unstructured content into DITA
- Perform document analysis; better to spend more time on this than not enough
- FM - look into using the Remove All Overrides command to clean up files
- Prototype project should not be the first book you want to convert. This should contain bits that represent all possible structures and components in your documentation set. Test and perfect the conversion, then test and prototype the various output options you plan to use.
- Use Mif2Go convert to DITA - export to Mif, then set up mif2Go config file to set up elements, wrapping syntax for Mif2Go, etc.
- Use FM Conversion table to map styles to elements, wrap elements into other elements, etc.
- Create a base topic for each section (Parse on Heading 2 or Chapter) to get files into DITA
- Conditional text boundaries need to map to to element boundaries. This is applied as attributes on those elements. It's often better to rewrite heavily conditionalized content into multiple paragraphs so you can apply conditions at the paragraph level.
- Frame's conversion tables don't map conditions. Any tools that do?
- Variables can become conrefs or just make them into plain text.
- Remove inline cross-refs and create relationship tables.
- The DITA 1.1 bookmap provides nodes for book-like structures like chapters, appendixes, and lists (TOC, index, etc.).
- If using Frame for PDF output, your TOC and index can be FM generated, otherwise they are generated by the tool (OT, or ?).
- If in doubt, shred your content to be more granular. It's easier to merge multiple topics together than break them apart later. Don't use "sections" if you can help it, they can probably be topics.
- Think about why you want to convert – based on current content, maybe only convert tasks, or other topics that are truly concepts or reference.
- How much material - manual or automated conversion
- How often you will convert – 1 time, or often
- Source material is in-house or external, both?
- How well or poorly structured
- Do a good doc analysis – go through doc set and see how well formed they are try to capture all use cases, what is in the docs? What do the styles mean?
- Too few or too many steps in conversion process – a step may have too much transformation , try small steps with iontermediate results to try out
- Prepare documents for DITA (to be good DITA) before conversion.
TOPIC 2: Options for generating output from DITA
- The OT provides scripts for generating, CHM, HTML, Eclipse Help, Java Help, PDF, and more.
- Basic output is not too hard, but styling/formatting can be very difficult for non-techie people.
- Suite Solutions offers great training for the OT if you want to learn how to maintain things yourself.
- CSS can be a simple way to customize OT output.
Options other than the OT:
- DITA2Go can be a replacement for the OT; from makers of Mif2Go
- XMetaL comes with OT bundled so it may be easier
- CHM to Web – generate HTML HELP from the OT and then use a template to convert to WebHelp
- FrameMaker can be the easiest way to generate PDFs from DITA even if you're not using FM for authoring.
- DITA-FMx provides extended PDF/book publishing features.
TOPIC 3: Authoring tips and ideas
- Author Assistant from SDL - Grammar Checker requires tweaking (free download for FrameMaker 9)
- Capture "what do I do now" moments – what do you do when something does not fit the model. Good to review later and share with others.
- See Megan's SVDIG presentation on creating Supertasks (tasks with links to subtasks)
- Indexterms in prolog, become meta keywords; this is good for HTML. Indexterms inline are good for PDF/print. Decide which is more important. Once you move indexterms into prolog it's hard to get them back inline; investigate tweaking XSL to copy inline indexterms to prolog for both purposes.
- DITA-FMx and Oxygen provide element sensitive online Help for DITA documents. Makes it easy to learn how things fit together.
» Thanks to Lauren Katzive for taking notes!
Business: Remote access and virtualization, infrastructure products
Organization: Training (also Technical Publications)
Objectives: Temporarily add to functionality of XMetaL and the DITA Open Toolkit, eventually purchase a CMS to handle the same tasks (they have since moved to DocZone)
Requirements, Issues: Automate edit/review of training material, translate into multiple languages, PPT a required target, SCORM package required, search and link management issues
Key Tools: XMetaL, svn, custom tools produced in-house by Ben and others
Sample Custom Solutions: Excel/VBA macros, script to create stub topics to get writers started, search facility using JEdit, script to build SCORM package, semi-automatic transformation to PPT from DITA source
Sample Challenges: Customizing PDF output, multi-volume books, SCORM requirements, instructor requirement to use PPT
Possible Future Challenges or Barriers to Reuse: Training and publications departments are now using different CMSs (DocZone on Alfresco and Astoria)
Conclusions: You don't need $1 million in tools to achieve some of the key CMS functionality required/useful in a DITA environment. What you learn doing custom tool production will help you choose the right commercial CMS when that opportunity presents itself.
Eric Armstrong, Treelight Enterprises
eric at treelight dot com
June 9, 2010 at NetApp
Context-sensitive WebHelp using a "preview feature" in XMetaL
No user download required
Some customization required
Index, search, browse
Print (but only single topic)
Does not launch if WebHelp already open
Links work (go to appropriate page), but framework not operational
XMetaL IDs are long and complex; Eric created his own unique IDs
For More Information
Tutorial by Su-Laine Yeo of JustSystems: http://forums.xmetal.com
The demo page, to launch the CS help: http://www.treelight.com/dita/cs_webhelp/
Topic: The pros and cons of using DITA with a CMS.
Speaker: Bret Freeman, of JustSystems/XMetaL.
Topic: Overcoming Barriers to DITA Adoption: A Demonstration of XMetaL Author DITA Edition
Speaker: Yas Etessam, Blast Radius, www.xmetal.com
Presentation: XMetaL_DITA_SIG.pps [1.2MB]
Welcome to the SVDIG website. We will post notes from our meeting, and encourage others to add comments. Please let me know if you have any ideas to make this site more useful.
Citrix has provided the SVDIG with a GoToMeeting account so we can offer virtual attendance to our meetings. We really appreciate the use of this wonderful tool!
Thanks to our past hosts!
- Dell KACE
- What is “DITA for the Web?” | DITA per Day on Meeting: It Was With You All Along: Adaptive DITA!
- saprentice on Meeting: It Was With You All Along: Adaptive DITA!
- markg on Meeting: It Was With You All Along: Adaptive DITA!
- Mark van Wyk on Meeting: Canceled
- Tracy Baker on Meeting: Introduction to XSL-FO and the DITA-OT
- May 2013
- March 2013
- February 2013
- December 2012
- November 2012
- October 2012
- September 2012
- August 2012
- July 2012
- June 2012
- May 2012
- April 2012
- February 2012
- January 2012
- December 2011
- November 2011
- October 2011
- September 2011
- July 2011
- June 2011
- May 2011
- April 2011
- March 2011
- February 2011
- January 2011
- December 2010
- November 2010
- September 2010
- August 2010
- July 2010
- June 2010
- May 2010
- April 2010
- March 2010
- February 2010
- January 2010
- December 2009
- November 2009
- October 2009
- September 2009
- August 2009
- July 2009
- June 2009
- May 2009
- April 2009
- March 2009
- February 2009
- January 2009
- December 2008
- November 2008
- October 2008
- September 2008
- August 2008
- July 2008
- June 2008
- May 2008
- April 2008
- March 2008
- February 2008
- January 2008
- December 2007
- November 2007
- October 2007
- September 2007
- August 2007
- July 2007
- June 2007
- May 2007
- April 2007
- March 2007
- February 2007
- January 2007
- December 2006
- November 2006
- October 2006
- September 2006
- August 2006
- July 2006
- June 2006
- May 2006
- April 2006
- March 2006
- February 2006
- January 2006
- December 2005
- November 2005
- October 2005
- September 2005
- August 2005
- July 2005
- June 2005