At the April meeting of the Boston DITA Users Group, Anna van Raaphorst and her husband/partner Richard H. (Dick) Johnson, principals at VR Communications, Inc. (http://www.vrcommunications.com) presented remotely from California on the topic  "implementingDITA™ Setting the Stage: Creating DITA Projects That Will Scale Up."

Anna and Dick are the authors of the DITA OT User Guide, and they are preparing a new version supporting DITA 1.1 with an expected release next week. Look for it on their website and http://dita-ot/sourceforge.net/SourceForgeFiles/doc/user_guide.html.

We will include the User Guide in our new DITA Infocenter at http://www.ditainfocenter.com.

Anna has many years of experience as a tech writer, including structured writing with Framemaker. She was an early member of CM Pros and organized the 2005 Spring Summit, producing a Best Practice for Summit Organization. Dick has been a software engineer at IBM and Stanford (SLAC). Anna and Dick had done just one joint project before (a book about a California community), but their mix of writing and software programming talents was critical for documenting the Open Toolkit. Dick built a number of reporting and analysis tools (written in PHP) to facilitate their real-world implementations of DITA for clients. Dick's tools will be available for download soon on their website.

At DITA East 2006, Michael Priestley asked for volunteers to produce a User Guide for the OT, and Anna raised her hand. While the first version compiled a lot of available material on the OT, 85 to 90% of the latest version has been rewritten, including expanded versions of the Garage and Grocery sample docsets, which are the basis for VR Communications' tutorials and training workshops. 

Anna began by calling for complex projects to be managed with an elegant sophistication. Complexity can provide many benefits along with the challenges. With good information architecture, good planning, and a strong set of rules governing collaborative projects, DITA is a most powerful tool. She called it a "miracle."  Benefits include reduced costs, faster response time, and better integration, e.g., with translation tools. Challenges will tax a typical tech writer's comprehension (thus the importance of partnering with someone technical), and coordination (e.g., with subject-matter experts) may become costly and chaotic.

She described the OT User Guide as a relatively simple DITA project, with 300 topics in 20 chapters, organized into the demo bookmap specialization (not the new 1.1 bookmaps specialization). Publishing targets were XHTML, PDF, and HTML Help. The new version will be significantly restructured and add Localization (translation), Eclipse Help, and publishing XHTML to a frameset.  She has extended the "core vocabulary" (a set of glossary definitions or concepts) that she "conrefs" into many other topics as needed, providing a great deal of what she called "informal reuse." A number of the ant scripts used to produce the book are now included (with annotations) in the book. There are related links on some pages, always limited to external links (for internal links she recommends reltables). Unfortunately, these external links don't show up in the PDF.

A project for a major client was much more complex, including four major documents. They shared many common files that were conref'd between topics (formal reuse). Reuse included images, installation instructions, introductions, and object properties. Besides XHTML and PDF targets, they added JavaDoc and plan to do context-sensitive help (CSH). The build was a 3-tier process (levels of nested ditamaps), with separate ant build scripts for each doc.

Anna's "lessons learned" were to do two prototype projects before attempting a serious client project. The first should take 3-4 weeks, with all new content, at least 2 output targets, up to 50 topics, and involve 2-3 people, including an information architect.  The second should last 6-8 weeks, some new and some migrated content (here you learn how DITA differs from Frame and other tools). With at least 100 topics, it should focus on reuse, customization, linking stragegies, and perhaps specialization. It needs 4-6 team members, including at least 1 architect, 1 technologist, and 1 editor.

Anna promised to put her Powerpoint slides, Dick's tools, and an implementation of a simple TinyWeb server at http://www.vrcommunications.com/resources/

We will post the slides to the Boston page on the DITA Focus Area (http://dita.xml.org/boston).

She invited emails from members looking for support and further advice.