Notes from DITA Q&A Session (Annapolis CIDM Conference)

["Larsen, Seraphim L" <seraphim.l.larsen@intel.com>]

Title: Notes from DITA Q&A Session (Annapolis CIDM Conference)

Hello TC,

Below are my personal notes from the "DITA Q&A" session that took place at the CIDM Content Management Conference in Annapolis, 4/12/2005.

Regards,
Seraphim

Susan Self -- Three issues

• Equations --
• Don -- Can it be addressed with tool plugins?
• Don -- Are there other tools that are in general use for XML?
• Michael Priestley: try MathML?  Not the best solution, but it is a solution.  Perhaps MathML can be incorporated as a DITA specialization
• Best way is to submit a use case to the DITA TC
• Don -- You could conref a fig, and within the fig have an image referring to the GIFs
• Bruce -- Use some other tool to create MathML, and do a transform to bring it into DITA
• Audience -- Is there a transform to go from MathML to PDF?
• Don -- There are tools for generating different outputs (raster, etc.)
• Audience -- You can also conref to a library of commonly used equations set up as GIFs or other graphic format
• Glossary --


• Index --
• Don -- DITA does have a method for indexing, but you can also do it with conrefs.
• We do need some kind of documentation on some ways to generate indexes.  We don't have a set of "best practices".
• We can (and should?) do a white paper on one or two methodologies currently in use (for generating indexes)

JoAnn --

• Why use DITA instead of writing our own topic-oriented DTD?
• Don -- Described the experience of Tokyo Electronics -- Put in a lot of work but still have nothing to show for 18 months, and still have a system with bugs.  It's working now, but DITA could have gotten you there a lot faster.  DITA already has got all the bugs worked out. 
• Don -- DITA has already seen “combat experience”
• Bill (Idiom) -- Forgot what he said
• Audience -- Rapid prototyping and picking tools off the shelf -- being able to show results right away.
• Don -- Yes, many tools have DITA support built into them already.
• Don -- It’s an OASIS standard now -- this speaks of its maturity and available for service.
• Don -- DITA is well-tested and well-supported
• Audience -- But you still have to develop and maintain your specializations
• Michael Priestley -- Not necessarily -- you can get by with few or no specializations
• You don’t have to develop more specializations before starting -- you can start with the basic four topics
• Indi has done both (design your own, or use DITA) -- There is a huge difference.  DITA enables quick results.  DITA enables an iterative model, where you can make changes quickly and easily also.  DITA does not require the huge effort required by a full-custom system.
• Susan Self -- Going to DITA keeps you from staying in your own silo -- you are open to industry standards.  You share the burden of maintenance with the DITA TC.
• Don -- You become part of a large and growing community of users
• Seraphim -- Helps you to find tech writers with DITA skills already, instead of having to train someone on your own custom DTD
• Scott Tsao -- Aerospace industry -- requires many standards, published by many different organizations (govt., etc.).  These standards seem to be in conflict, and if they were in DITA, they could be unified -- presented using the same approach.  The different standards don’t match up well.
• Discussion of standards -- The industry can take off only if there are enabling standards in place.
• Audience (CEO of Xy?) -- But DITA should not attempt to become the “be-all, end-all” standard.  DITA should not attempt to replace or duplicate other XML efforts
• Michael Priestley -- Yes, but we don’t want to just use other standards (such as xinclude) that don’t give us what we need.  We have to build our own replacement mechanisms (such as conref) to get us by.  These were done because the standards in place did not have the functionality we needed for DITA.
• Seraphim -- The perlmod repository of Perl modules is a good model.
• Michael -- Yes, this is exactly what OASIS has in mind, and the model we are striving toward.
• AR -- How do we set this up?

Travis Houck (HP) --

• Graphics -- How do these work in DITA?
• Don -- If you are referencing the graphic, you can just pass it along to the tools, and your XSLT takes care of it.
• Travis -- What about SVG?  Can you author it inline?
• Michael -- Hard to imagine SVG inline.   But you can set up domains to handle it.  (?)  (Couldn’t really follow this.)

Section 508 (?) Compliance --

• Don -- IBM specifically addressed some issues here. 
• Couldn’t really follow this -- too esoteric for me!
• The DITA toolkit generates Section 508-compliant HTML

Susan Self --

• Indi’s “Visual Task” is very generic -- can it be put into the spec?
• Michael -- We’re looking at this kind of thing as a future part of the spec.  Perhaps a more generalized version of Topic, to be parallel to the existing Topic.
• When two groups have a similar specialization, but some unique elements that cannot be integrated, you can introduce an intermediate base class that includes the common elements, and specialize the two specializations from that base class.

Salesforce.com --

• Project Management issues…  How to deal with this?
• Michael outlines with maps -- he creates maps, and then populates it with topics.
• We need to discuss these kinds of tools more, and how to use them with DITA
• JoAnn -- But why isn’t this part of a content management system?
• Don -- Didn’t really understand his answer
• JoAnn -- The CMS vendors need to provide map editors -- they need to come up ways to edit that make sense with DITA



• Discussion of Maps --
• How to organize topics?
• Most useful to gather stuff into maps
• This can be done automatically -- maps can be generated -- most useful for cases such as airplane parts or encyclopedias, where the topic lists are extremely large.
• It is the role of the information architect to decide how this is going to work for a particular project.  You need to chunk it properly.
• JoAnn -- The transition is that you are no longer assigning writers to author books.  You are changing to topics.
• Lots of communication is needed between the information architect and the writers.
• The information architect is the one who “has the whole project in his head”
• What tools do you use to create your map?
• Indi and Michael use Epic Editor
• The questioner uses Xmetal
• You can hand-code them
• You can auto-generate them
• Michael -- the tool vendors are beginning to support this

Seraphim -- What do you need to make this work?

• Editing Tools --
• You can track these things on XML Cover Pages -- vendors make announcements there
• Vax @ sourceforge.net
• Syrna from Syntex
• Epic Editor
• Adobe FrameMaker in conjunction with Kay Ethier’s Yahoo Group (Frame DITA Users)
• XML Mind
• XML Spy
• Xmetal -- requires some customization
• Oxygen -- it all works


• The DITA Open Source toolkit -- available on the Fact Sheet
• Many free tools are available, described in the ReadMe -- such as Saxon


• It's difficult to talk about these things in detail, for several reasons --
• The TC is not in a position to "take sides" in regard to different tools and vendors
• Companies who have already developed working systems are not in a position to reveal details, because it could reveal details of internal processes, which could be advantageous to competitors.

___________________________________________________________
Seraphim Larsen                  CIG Technical Publications
Technical Writer                          Intel Corporation
(480) 552-6504                                 Chandler, AZ

The content of this message is my personal opinion only.
Although I am an employee of Intel, the statements I make
here in no way represent Intel's position on the issue, nor
am I authorized to speak on behalf of Intel on this matter.
___________________________________________________________