What to check for when selecting tools for use with DITA

Note: This page is a work in progress, for brainstorming purposes only. It is a collection of ideas for a document that could be written about tools supporting DITA. Statements on this page have been contributed by individuals, have not necessarily been reviewed by others, and do not represent the views of the DITA Adoption TC as a whole.


There are a variety of tools on the market that claim to support DITA. However, some tools provide more complete support for DITA than others. Before selecting the tool or tools you would like to use, check the details listed below to ensure your tool set sufficiently supports the DITA features you intend to use.

<<Note to person using this material (near beginning of the doc) about benefits of compliance and also that if they are not needed all the features or open standards to allow them to switch tools (portability) they need to consider as they use this doc.>>

<PBG: In general, we need to be careful that this document isn't seen as creating new requirements that are different or which go beyond the requirements in the DITA specification from the DITA TC. We should avoid use of the terms "required", "requirement", "must", "test", "validate", and "compliance" in this document. Moving to more of a checklist that is designed to aid individuals and organizations select tools that meet their needs would be a better approach.>

Scoping DITA compliance

<PBG: This isn’t a good heading. What does "scoping" means here. We might want to avoid the word "compliance" since that suggests something more formal and stricter than what we will probably be able to do with this document without a huge amount of work. Some suggestions for alternatives: "Evaluating DITA-awareness" or "Reviewing DITA support for the DITA standard".>

What should be tested?

<PBG: What should be "considered", "reviewed", "evaluated" would all be better choices of words here.>

Which tools and/or components should be tested?

Who is the intended audience?

<PBG: It might be better to focus this document on users and not on vendors for the first release at least. Vendors should be more focused on the DITA specification.>

<PBG: The "test suite" should be a separate thing. Development and maintenance of a test suite is going to take a lot of time and effort, and it is likely to delay the release of a checklist if the two are too tightly tied together.>

Generic requirements that apply to all tools

This section lists the requirements that must be met by any tool claiming support for DITA. The requirements listed in this section are not specific to any component or aspect of working with DITA content.

<PBG: I'm not sure I see the point of this section. First, what does it mean for a tool to "implement a DTD"? Does that mean it includes the DTD in its distribution? What about a generic XML tool that can handle any DTD--in what way does it "implement a DTD"?>

<PBG: Under what auspices can we talk about "requirements" that "must" be met by tools? As far as I understand it, "requirements" and "must" are words with specific compliance meanings when related to the DITA standard, and the DITA standard puts requirements on DITA content, not methods or tools for creating that content. And insofar as there are requirements in the DITA standard, why should our document repeat them?>

<PBG: What is the plan for fleshing out this section with lists of features that must be supported by each spec? Are we going to go through the specs and pick out the MUSTS (which aren't really clear in DITA 1.0 and 1.1) and list them and only them? In what way is that useful to users?>

  1. For each release of the DITA specification that the tool claims to support, the tool must implement the latest version of DTDs and/or schemas that apply to that DITA release.
  2. A tool claiming to support DITA 1.0 must support the following DITA features:
    1. TBD list of features to be supported (extract from specs)
    2. TBD
  3. A tool claiming to support DITA 1.1 must support all DITA 1.0 features plus the following additional features:
    1. TBD list of features to be supported (extract from specs)
    2. TBD
  4. A tool claiming to support DITA 1.2 must support all DITA 1.1 features plus the following additional features:
    1. TBD list of features to be supported (extract from specs)
    2. TBD

DTD/Schema

  1. Does your product have full support for the DITA 1.2 base DTDs and Schemas (Concept, Task, Reference, Map, Bookmap, Task, General Task)?
  2. Does your product have support for other 1.2 specializations?
    1. Glossary improvements
    2. Learning information types (Overview, Content, Assessment, Summary)
    3. Machine task
  3. Are both Tasks, strict and general, available? If no, which one is available by default?

Referencing

  1. Improvements to Conref – range, push
  2. Keyref
  3. Glossary and terminology handling

Downstream processing (publishing)

  1. Is the DITA-OT an option? If so, which version?
  2. Have you included any customized transforms in your publishing suite?

Organizational configurations

  1. Constraints
  2. Subject scheme

Requirements for topic development

This section lists the requirements that must be met by any tool or component claiming support for the creation and/or modification of DITA content (authoring and editing tools).

<PBG: I don't know why any of these are "must". Are we saying that the DITA spec does not allow someone to create DITA content using Notepad? We should get rid of "must" and "requirements" and frame this as a checklist of things a user might want to consider, depending on their needs, when evaluation a tool. That is, this entire section should be rephrased to be more like the "Support for management of topics within a repository" section where we list questions a user should consider.>

  1. All content created, saved, and generated by the tool must be valid DITA XML as validated against the DTD or schema.
  2. When creating a new topic, the tool must associate the topic being created with the relevant DTD or schema that applies to the topic type being created.
  3. At any time during the authoring process, the tool must expose only those elements that are valid in the context of the content being edited.

    <PBG: Items 1, 2, and 3 are generic requirements for an XML aware authoring system. Why not replace these three points with "A DITA authoring tool should be a fully compliant XML authoring tool" or perhaps "The tools should be able to create, generate, or save valid DITA XML documents.">

    [GLJ: I prefer to keep them separate, because users who are new to DITA are usually also new to XML and have no idea how an XML application should behave.]

  4. The tool must support the construction of a unique ID for each DITA topic and for elements within the topic. [Gershon> This is a standard XML requirement; why do we say it?]

    <PBG: This is a potential "nice to have" feature of an authoring tool, but it is not a requirement (and certainly not a "standard XML requirement", especially given that ids within a topic aren't XML ids).>

  5. The tool must not insert product-specific content or code into a DITA topic that may make the topic difficult to edit with other DITA-compliant editors.

    <PBG: I don't understand this one. If a tool is XML compliant, what could it possibly insert that couldn't be handled by another XML compliant tool?>

  6. The tool must not insert application-specific elements or any other application-specific code into a DITA topic, such as name-spaced elements used to track changes, that may cause processing to break. Note that the DITA specification does not support namespaces; therefore tools should not use them.

    <PBG: DITA doesn't support change tracking, so users wishing to produce DITA content for interchange with other tools should know that they cannot use change tracking, or at least they need to resolve the change tracking (e.g., accept all changes to generate the latest view) to produce DITA content. As long as the tool makes it easy to avoid using change tracking and/or to remove any change tracking information that was inserted, how can we say that a user shouldn't use a tool that provides this extra capability?>

    [GLJ: Users new to DITA are usually also new to their new XML editor. They don't know that change tracking is unique to the editing tool. I have had many projects where authors processed their content that included change tracking and then got upset when they got errors, and/or strange content, in the output. We need to make users aware of this issue.]

    <PBG: The statement that the DITA specification doesn't support namespaces is confusing. The DITAArchVersion attribute is namespaced as are the xml:lang and xml:space attributes. Besides, there is nothing in the DITA spec that says that one cannot use namespaces in, say, ones own specializations. It's just that all the elements in the current DITA DTDs and XSDs are in no namespace. So this statement should be deleted.>

    [GLJ Agreed. I've removed it from the article.]

  7. The tool must support the addition of specialized DITA DTDs and schema into the editor for author selection.

    <PBG: I don't know what this is saying. What does "addition of ... DTDs ... into the editor" mean? Besides, we shouldn't be saying that a tool that is, say, hard-wired to work on DITA topics but that does not allow for specializations isn't DITA-compliant. Instead, we should be explaining the advantages and use cases for support for handling arbitrary specializations and let the user decide if this is important to them as part of their tool selection.>

  8. The tool must support the valid construction of DITA maps and specializations thereof (e.g. bookmap) in the editor, including the addition of topicref attributes to the map.

    <PBG: What is this saying other than the editor should be able to edit documents that happen to be dita maps? This doesn't seem to be a particularly useful thing to say any more than saying that the editor should be able to edit documents that happen to be dita topics, and we don't say that, so why say this at all?>

    <PBG: We shouldn’t prohibit a tool that supports map, but not bookmap. We should encourage full disclosure about what a tool does and does not support and encourage users to compare their requirements against that, but we should not move to make new requirements that are not in fact required by the DITA specification.>

  9. The tool must support the insertion and modification of content references (conref).
  10. The tool must support the addition of images to a DITA topic.
  11. The tool must support the insertion or modification of valid cross references to:
    1. a topic or specialization thereof
    2. an element in the same topic
    3. an element in another topic

    <PBG: What are items 9, 10, and 11 saying other than the tool should support authoring elements and attributes--which we'll have covered by saying that the tool should be an XML authoring tool.>

  12. The tool should support the ability to "hide" DITA elements that are not used in the authoring environment (even though such elements are part of the information model (topic or map type) being used).

    <PBG: This isn’t something that is a requirement. Perhaps it is a good thing to support and perhaps this is covered by the use of the word "should" here rather than the word "must". On the other hand this entire list started out with "requirements that must be met by any tool" and this isn’t such a requirement.>

  13. The tool should have the ability to display code view as well as any number of rendered views, which should include resolution of cross references and content references.

    <PBG: What does "display code view ..." mean, and how would a user know if this is a feature they should care about? And is this a DITA requirement or a general XML authoring issue?>

  14. The tool must generate interoperable content (i.e., no namespaces or proprietary attributes that are not defined in the supported DITA release).

    <PBG: This should read "The tool must be able to generate interoperable content that parses against the DTDs or XSDs in the supported DITA release." There is no reason to mention namespaces (we do havenamespaces in the DITA doctypes on the DITAArchVersion, xml:space, and xml:lang attributes) or "proprietary attributes" as that's all covered by saying that the result must validate against the DTDs.>

    <PBG: It might be preferable for the discussion to encourage evaluating sets of tools together. The burden of being interoperable should not be placed exclusively on one tool or another. What matters is whether a particular tool will interoperate with other tools that the user wants to use (e.g., authoring tools with the chosen CMS) and then can the overall system produce DITA-valid content for external interchange. For example, a user may well want to use change tracking in-house, in which case the user must insure that all the in-house tools can handle that. Then, as long as the system makes it easy to prepare the finalized content for external interchange (without change tracking, given that there is no DITA markup to handle change tracking), this may be the best solution for the user.>

  15. When modifying an existing DITA topic or map, the tool must preserve the original line and character breaks and other white space that the author created (not modify the appearance of the file).

    <PBG: This statement is misguided and misleading. Here is what I suggest we say: XML aware editors are not text editors, and there is no reason in general to maintain line breaks and white space except when xml:space="preserve". When authoring something like a paragraph in such an editor, the user just enters text without line breaks, and the view in the edit window automatically wraps depending on the size of the edit window. When such a file is written out to a file system, it is customary for the tool to introduce line breaks to make the resulting file easier to view and handle as a text file. (Some tools provide various parameters to control the maximum line length or to turn off introduction of line breaks altogether.) When the document is read back into the XML aware editor, those introduced line breaks are removed so that the content once again wraps according to the edit window size, and this is generally the preferred behavior. To allow an author to be able to edit and maintain specific line breaks and other white space, the XML standard defines an xml:space attribute, and XML compliant editors are expected to maintain white space within elements that have specified xml:space="preserve". The DITA DTDs have set xml:space="preserve" on DITA's <pre> element, so XML editors should support white space preserving behavior within the <pre> element. For other elements, when you add a word at the beginning of a paragraph and the rewrite the document to the file system, the line break introduction may well create a file in which every line of that paragraph differs from that in the previous version. Therefore, some functions, such as simple text-based differencing tools, will not work optimally. If this is a consideration for a given installation, one should either consider getting an entire family of tools (including differencing ones) that are XML aware, or consider using an authoring tool that allows the necessary control over handling of white space.>

Support for topic and map processing

Gershon: This section needs a lot more thought and work. I don't think we should prescribe the processing architecture -- we don't care whether or how the tool merges the topics for styling, as long as the outputs are correctly produced. I think we should rather list the output formats that should be supported, as well as the DITA features that should be correctly processed (which we already say well). Some of the above bullets (the merging stuff mainly) only apply only to PDF type outputs and are not relevant to the online type outputs.

<PBG: I agree with Gershon that this section needs more work, so rather than make comments on the individual points at this time, I'll only point out in response to Gershon's comment that merging is only irrelevant to online outputs when you are maintaining the input chunking for output, but this is not the only option for producing online output, so in general, merging is relevant to online outputs.>

Support for management of topics within a repository

<PBG: What follows is pretty generic and not at all DITA specific. A generic buyer’s guide to XML CMS systems seems like an odd thing to be coming out from the DITA Adoption TC. None of these are requirements other than the need to maintain documents as valid XML and valid DITA documents. This is more a list of "nice to have" or "things to consider".>

As the amount of your content grows and more people become involved in the documentation process, you may need a tool that enables you to manage topics, including search, support for collaborative work, version control, and translation management.

While the capabilities you may need obviously depend on your specific needs, these are some general issues you should check:

Gershon: I think we're missing 1) native XML database versus ralational database and 2) search that understands the XML elements and attributes. I don't fully understand some of the info listed in the above bullets.

* Defining compliance with content management systems

Support for translated content

If you write content that will be translated, make sure that your tool chain supports editing and publishing the translated versions of your DITA documents.

Check if:

Translation of DITA documents

As DITA is an XML vocabulary, it is generally translation-friendly and many CAT (Computer Assisted Translation) tools can be used to translate DITA files. Nevertheless, you should check these items:

When using a CMS, the following features should be considered:

Considerations for a test suite

<PBG: A suite of sample documents or a test suite? They are very different things. Creating a suite of sample documents that exercise many/most/all of the DITA features might be a worthwhile task.>

Compliance Scheme

Claims of DITA support are not particularly useful if there is no practical way for a new DITA adopter to assess the accuracy of the claims. Some sort of compliance scheme would be required, where claims could be tested and challenged. The idea of compliance scheme is discussed in detail on the ComplianceScheme page.

Components of a test suite for DITA compliance

Placeholder section that will be used to scope and design a possible test suite to be used with this article to validate tools for DITA compliance.

Future activity: Build a validator for DITA files and maps including specializations

Draft Possible Compliance Score Matrix for DITA Editors

Feature

Level 1

Level 2

Level 3

Level 4

Validates against OASIS DTDs or XSDs (version to be specified)

x

Suggests valid elements at cursor position

x

Opens standard DITA documents and saves standard DITA documents

x

Allows re-use of DITA topic elements in ditamap

x

WYSIOO graphical topic editor

x

x

WYSIOO graphical table editor

x

x

Allows re-use of DITA topic elements through conref

x

x

Opens specialised DITA documents and saves specialised DITA documents

x

Supports constrained DITA documents (1.2+)

x

Tree editor for ditamaps and bookmaps

x

x

Graphical relationship table editor

x

x

Allows authors to follow links (xref, conref, etc) to edit targets

x

x

Context-sensitive Help linked to language reference

x

x

Allows creation of xref through dialog box target selection

x

x

Allows re-use of ditamaps through mapref

x

x

Drag-and-drop ditamap and bookmap editor

x

x

x

Drag-and-drop relationship table editor

x

x

x

Search and replace through topics referenced in a map

x

x

x

Supports application of conditionalising attributes through controlled values

x

x

x

Supports application of other metadata attributes through controlled values

x

x

x

Displays relationships between content and its re-use

x

x

x

x

Displays usage report for topics and media

x

x

x

x

Allows content to be freely organised by moving and renaming files without breaking links

x

x

x

x

In-editor filtering: display or hide content based on element attributes

x

x

x

x

factSheet (last edited 2011-10-24 05:58:13 by joann.hackos)