DITA Visual Specialization Manager contains comprehensive modeling functions. In productivity area, it provides benefits in terms of lesser time, optimal quality of deliverables, and single-sourcing of the model by its ability to export DTD and XML Schema. The main features of this application are listed as follows:

• Wizard-based Visual Editor for DITA specializations with support of structural, domain and attribute specializations
• Import of existing specializations from DTD
• DITA model validation (checking for validity of specialization)
• Export of managed specializations to DTD or XML Schema
• Export of Specializations in the form of DITA OT plug-in
• Integration with version control

All these benefits and functionalities have been developed to give substantial support to Information Architects and Documentation Project Managers in designing and maintaining their DITA specializations. It is done by providing a wizard-based visual editor for DITA information
types. The development of these functionalities has been made possible through a mix of technological expertise and practical experience gained from various DITA projects.

Besides the standard commercial license for DITA Visual Specialization Manager, *instinctools offers a free-of-cost non-commercial license for development and maintenance of publicly available DITA Specializations and a time-limited evaluation license.

For first information on working with DITA Visual Specialization Manager for typical modeling tasks, we have provided tutorial videos for creating Model Projects, Shell DTDs, Structural and Domain DITA Specialization, and Export to DTD and DITA Open Toolkit on website: http://www.ditaworks.com/Vids.

Downloads for DITA Visual Specialization Manager (for evaluation and
non-commercial free-of-charge use) are available from http://www.ditaworks.com/dl.

For more information about DITA Visual Specialization Manager, please
visit http://www.ditaworks.com/modeling or write to info@instinctools.com.

DITA Visual Specialization Manager is planned to be released this week, but now you have a possibility to get a first preview of available functionality by watching some fresh screen casts published on DITAworks website. These demos cover following functions of DVSM:

Creating Modeling Project
Creating new DITA Infotypes
Performing Structured DITA Specialization
Performing Domain DITA Specialization
Export of Managed Models to DTD and DITA Open Toolkit

We are looking forward for your feedbacks on features presented there.

I remind that DITA Visual Specialization Manager will be available free-of-cost for non-commercial usage and for architects developing DITA models that are publically accessible.

Stuttgart, Germany, November 5, 2009 — *instinctools GmbH, a company providing software solutions and services, has been previously instrumental in bringing an innovative structured documentation solution in the form of DITAworks Documentation Application in the market. They have also brought productivity enhancement benefits in documentation area like full Eclipse IDE integration with their documentation application DITAworks. Now, they have decided to make a contribution to the DITA community by providing their DITAVisual  Specialization Manager totally free of charge for the purpose of development and maintenance publicly available DITA Specializations. This will provide a much needed impetus to DITA standard by lowering barriers to DITA adoption as a result of simplification of the DITA specialization process.
The DITA Visual Specialization Manager contains comprehensive modeling functions that allow development and maintenance of project specific documentation models (DITA Specializations). This application opens a new dimension in the ease of customizing DITA to specific needs in a user-friendly way. It simplifies the DITA specialization processes while providing productivity benefits in terms of lesser time, optimal quality of deliverables, and single-sourcing of the model (export of DTD and XML Schema possible). Furthermore, it can facilitate an integrated environment with 100% DITA-based tools like DITAworks. The main features of this application are listed as follows:

• Wizard-based Visual Editor for DITA specializations with support of structural, domain and attribute specializations
• Import of existing specializations from DTD.
• DITA model validation (checking for validity of specialization)
• Export of managed specializations to DTD or XML Schema
• Export of Specializations in form of DITA OT plugin
• Integration with version control

All these benefits and functionalities have been developed to give substantial support to Information Architects and Documentation Project Managers in designing and maintaining their DITA specializations by providing wizard-based visual editor for DITA information types. The development of these functionalities has been made possible through a mix of technological expertise and practical experience gained from various DITA projects.

This free-of-cost license for DITA Visual Specialization Manager will be limited to development of or working with models available publically and prohibit any commercial use of the tool other than evaluation. The license will be made available starting from the first week of December.

For more information about DITA Visual Specialization Manager from *instinctools, please visit www.ditaworks.com/modeling

I would not go deep into the details of Eclipse Help subsystem now. It will be a subject for another blog post which will come later. The only thing I’d like to emphasize now is that Eclipse Help subsystem expects documentation to be provided in Eclipse Help format. This documentation can be used in two ways:

• In the “book” mode or so called “Infocenter” mode, where users can browse documentation structure, search through the documentation, browse documentation index. You can explore this mode with Eclipse online documentation.
• As context-sensitive help, when appropriate help page is shown depending on the application context (window).

We use DITA Open Toolkit in order to transform DITA based documentation to Eclipse Help format.  This transformation works well for the Infocenter mode out-of-the-box . DITA OT creates special Eclipse plug-in out of the DITA documentation.  This plug-in should be distributed with an Eclipse RCP application.

At the same time, additional XML objects need to be created in order to provide context–sensitive help. These objects describe the association between context IDs which are declared in the RCP application source code and the list of links to related topics and optional text description of the context. The main complexity here is synchronization of IDs used in source code with context definitions, taking into account that IDs and documentation are created by different and often distributed teams. This is why we have to maximally automate Eclipse Help context creation and maintenance.

The process we are using for the RCP documentation development can be split in two parts.  The first part needs to be done by RCP developers and the second part is documentation team’s responsibility.

Part 1 (RCP development team)

1. Assigning context IDs to UI widgets in RCP application source code
2. Exporting context IDs data and delivering them to documentation team
3. Creating Eclipse Help plug-in in RCP application where documentation will be stored

Part 2 (documentation team)

1. Creating DITA documentation
2. Creating specialized DITA map for editing Eclipse Help contexts
3. Importing context IDs provided by RCP development team
4. Creating context definitions
5. Publishing Eclipse Help content to the plug-in provided by RCP developers

To simplify first group of activities, we have created a special Eclipse plugin that should be installed to RCP developers’ environment. Second group of activities is automated by DITAworks.

Let’s consider these steps in more details.

1.1 Defining Contexts IDs in Eclipse RCP Source Code

As a first step, RCP developers should assign unique context ID to UI controls. Each UI component can have one context ID.  Later, it will be possible to link several related topics and provide a text description for each Context ID.  Context ID assignments can be static or dynamic.  Below, I shortly explore each of the methods.

Static contexts can be defined using setHelp method in org.eclipse.ui.help.IWorkbenchHelpSystem which will associate a context ID with a Control, IAction, Menu, or MenuItem. The context ID should be fully qualified with the plug-in ID. For example, the following snippet associates the id “com.example.helpexample.panic_button” with a button in the application.

PlatformUI.getWorkbench().getHelpSystem()
                        .setHelp(myButton, "com.example.helpexample.panic_button");

Dynamic contexts are calculated automatically during run time.  This can be archieved through the implementation of org.eclipse.help.IContextProvider interface which ensures dynamic Context ID calculation.  It is also possible to use the following code:

PlatformUI.getWorkbench().getHelpSystem()
             .setHelp(control,
                      HelpUtil.getContextId(IHelpContexts.MY_CONTEXT1,
                                            "my.application.main.ui"));

This method is recomended for dialogs but works well everywhere.

Dynamic context allow us to store all context IDs in one place which can be then delivered to the documentation team e.g. in an XML file which can also contain additional information (comments, descriptions etc.).

To simlify and speed up help related activites for RCP developers, we’ve implemented a special Eclipse plug-in which should be deployed to RCP developers’ Eclipse environment. All functions provided by this plugin can be found in right-click menu item “Eclipse Help” which is available for java projects, java packages or java classes:

Let’s take a look at the functionality provided by this plugin:

Convert Static contexts to Dynamic

This operation will find all static contexts in the selected scope (project, package or java class) and convert them to dynamic contexts. When a developer executes this function, a special wizard will be started which will search for static contexts and present them in the dialog form.  There, the developer will see all static contexts which are found in the application and will be able to modify values automatically assigned by the wizard HelpKey.

The wizard will also allow the developer to specify a class where constants will be defined.

Assign contexts for new components

This operation will search for new UI components that do not have Context ID assigned to them yet.  Then, developers will be able to modify autogenerated IDs and generate a Java code which will assign these IDs to the corresponding UI widgets.

1.2 Delivering Context IDs Data to the Documentation Team

In this step, RCP developers should transfer a file with Context IDs definitions to the documentation team. Eclipse plug-in described in the item 1.1 above provides Export Contexts to DITAworks function that  should be used in order to export context IDs to the documentation team.  When this function is executed, a wizard will be started which will search for contexts and will allow to edit descriptions and make comments. These should be delivered to the documentation team. After this operation is done, a directory, where context definitions will be stored, should be selected. Merging with existing context definition file is also supported by the plugin.

Exported file with Context IDs should be provided to the documentation team. We suggest to use version control in order to organize smooth sharing of this file between development and documentation teams.

1.3  Creating Eclipse Help Plug-in in RCP Application

RCP developers should create an eclipse plug-in project in Eclipse IDE and link it from the target platform of the RCP application.  This plug-in project will be used to exchange information between the development and the documentation teams. More detailed description of plugin creation procedure can be found in Eclipse online help.

After creating Eclipse Help Plug-in, the plug-in project should be shared with documentation team through the version control (CVS, SVN or any other which is used in your organization). Later, documentation team will use this project as an output for Eclipse Help publishing.

2.1  Creating DITA Documentation

This step is done by the documentation team which should create required deliverables, DITA topics and maps. It can be executed in parallel to the RCP development team activities 1.1 - 1.3 described above.

2.2  Creating Specialized DITA Map for Editing Eclipse Help Contexts

As it was described in our previous post, we use specialized DITA map object to store Eclipse Help context data. This allows us to store context data in DITA and use available tools and validation mechanisms. DITAworks provides EclipseHelpPluginMap specialization that should be used for these kinds of maps. To create it in DITAworks, start  “New Map” wizard, type a title, choose document type “eclipsehelpplugin” and choose a folder to store new map.

As a result DITAworks will create a new map with the eclipse help plug-in structure.

2.3 Importing Context IDs Provided by RCP Development Team

DITAworks already provides functionality that should be used for importing Context IDs data provided by the development team. It can be done by using DITA | Import Context IDs wizard available in the right click menu on a content project.  This wizard allows to specify a file for import, define the destination folder. It also supports file merging in the case of context IDs already imported earlier.

2.4 Defining Contexts

In this step, the documentation team should create context definition using DITAworks map editor.

2.5  Publishing Documentation to the Plug-in Available for RCP Developers

In this step, DITA documentation should be published to the plug-in which was created by RCP developers in the step 1.1.  The publishing can be started by selecting a map and choosing  Publish » Publish to… from the right-click menu.  It is necessary to select ”Eclipse help with contexts” format as a type of deliverable and the plug-in root folder as a publishing destination.

Conclusions

This is how we facilitate collaboration during Eclipse Help documentation development. We would very much appreciate any feedback on the approach described above. We also welcome you to share any experiences which you might have regarding complex RCP documentation development.

Defining glossaries

Glossaries in DITA are defined using <glossentry> elements that represent a separate glossary entries. glossentry is defined as independent topic type specialized from standard DITA topic.

We have point out to significant difference about how glossaries are defined in DITA 1.1 and DITA 1.2.

In DITA 1.1 glossentries are quite simple topics consisting of glossterm and glossdef elements + optional related-links. As in DITA 1.2 content model of glossentry is pretty much developed, providing possibility to define abbreviations, synonyms and s.o.

In both DITA 1.1 and DITA 1.2 glossentry elements can be defined either in separate files (one entry per file) or inside of DITA composite topic (<dita> element).

Example:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN"

 "glossary.dtd">
<dita>

 <glossentry id="Term_1_dita_glossentry_3">

    <glossterm>Term 1</glossterm>

    <glossdef>Definition 1</glossdef>

 </glossentry>

 <glossentry id="Term_2_dita_glossentry_4">

    <glossterm>Term 2</glossterm>

    <glossdef>Definition 2</glossdef>

 </glossentry>

 <glossentry id="Term_3_dita_glossentry_5">

    <glossterm>Term 3</glossterm>

    <glossdef>Definition 3</glossdef>

 </glossentry>

</dita>

Later glossentries are linked to publications using glossarylist element of bookmap.

Example:

<backmatter>

  <booklists>

    <indexlist/>

    <bibliolist/>

    <glossarylist >

        <topicref format="dita" href="../../TBD/Glossary_2.dita" toc="no" type="glossary"/>

    </glossarylist>

  </booklists>

</backmatter>

In DITA 1.2 support of glossaries is much more mature (see http://dita.xml.org/sites/dita.xml.org/files/DITA1.2GlossaryTerminologySpecialization.pdf). Content model itself is more developed and there is a way to make references to glossary entries from content using <term> element.

Publishing glossaries

DITA does not define any restrictions or guidelines as to processing of <glossarylist>. It is completely responsibility of processing engine. In DITA Open Toolkit 1.5. glossaries have no special processing and are published like ordinary topics. So we can say that glossary publication is not supported properly in DITA Open Toolkit yet.

Support in DITAworks

DITAworks 1.1 is based on DITA 1.1 and it uses all data structures available in DITA 1.1 to define glossaries. Possibilities of DITA 1.1 glossaries are enough to be able to define new glossary terms and link them to published documentation. There are some difficulties with linking to glossary topics from <term> elements though.

In DITAworks version 1.2 we plan to fully support DITA 1.2 and users will get all advantages of new support of glossaries in DITA 1.2 starting from this version.

As to publishing glossaries:  DITAworks 1.1 extends standard DITA Open Toolkit and provides convenient way to generate standard alphabetically grouped glossaries in our books based on <glossarylist> element.

Presentation describes the issues in producing documentation for Eclipse RCP applications and how DITAworks addresses these issues by introducing single source publishing approach. Presentation addresses how certain specifics of Eclipse Help format are managed by DITAworks.

The event took place on the premises of Wirtschaftsfoerderung Region in Stuttgart and was organized by *instinctools GmbH in a joint effort with WeigleWilzcek, Eclipse Foundation and Wirtschaftsfoerderung Region Stuttgart.

You can download the presentation from the following link: Eclipse_stammtisch_2009_06_041

Thank you for everyone who attended the event and especially for Ralph Muller.

On June 22, 2009 *instinctools will present released DITAworks 1.1 as an important innovation on the 9th Single Source Forum in Munich.

This event is an ideal opportunity for visitors from all kinds of business areas to get information on challenges and innovations in the documentation world.

This year, emphasis is placed on new developments in the provision of information. How suitable are Web 2.0 technologies for the documentation environment? How can clients be directly involved in the creation process? And how do collaboration platforms promote the exchange of information?

Answers to these questions are given by acclaimed field experts in the form of lectures and practice examples on themes such as virtual team work, collaborative tools and user involvement.

Professor Dr. Volker Markl from the Technical University of Berlin opens the program with an exciting insight into the intelligent search machines of tomorrow. To round off the day, a panel of experts from science and business will discuss the latest trends in technical documentation.

In the accompanying exhibition, renowned software manufacturers present their proven tools and interesting new developments.

Visit our booth on Single Source forum..

More about Single Source Forum

About Eclipse Help

The Eclipse Platform includes its own help system based on an XML table of contents referencing HTML files.  This is a standard way to document Eclipse-based software products.

But eclipse help format is not reduced to usages only inside of Eclipse platform. It is available as standalone server solution and can be used for providing ANY help content via Web server. Eclipse help system provides such important functions like navigation through TOCs, search, indexing, bookmarking and s.o.

When Eclipse help is used for documentation of Eclipse-based software, it allows much more sophisticated mechanisms for context-dependent help definitions like: search expressions, contexts, so called cheat sheets and s.o.

Additionally, due to component-oriented architecture of Eclipse, Eclipse help is structured in form of plugins that can be independently deployed and interlinked. This enables creation of scalable documentation that fits to complex product configurations.

Eclipse Help and DITA

DITA as single-source architecture opens a promising approach for maintaining all your documentation in single format. Eclipse help as one of the publishing formats can address needs of context dependent application help as well as generic online help.

DITA Open Toolkit provides a way to transform DITA maps and topics into Eclipse help plugins, but these possibilities are quite limited. Namely DITA OT will generate a TOC file and set of HTML topics linked to source map, but it does not address following important specifics of Eclipse Help:

• Definition of contexts (used for context-dependent help)
• Interlinking topics between several Eclipse help plugins
• Definition of search phrases
• Definition of cheat sheets
• Tuning of plug-in contents (Manifest properties, amount of TOCs, indexes, contexts and s.o.)
• Some other advanced features of eclipse help.

These limitations are hindering adoption of Eclipse help as publishing output format for DITA content.  They need to be addressed if we want to use the full capability of Eclipse help system and this issue can be seen as a current challenge for DITA-oriented tooling.

Eclipse Help and documentation process

Another main challenge in the area of Eclipse help can be found in organization approach to documentation process. In tasks that require definition of context-sensitive help, authoring team needs to work closely together with software development teams. This is required because software developers need to integrate IDs of help topics and contexts inside of software UI code. Same IDs should be mapped to help content created by authoring team.

The documentation process and software development process very often have iterative nature. So the synchronization of IDs, which are defined in software code and in documentation itself, can become a serious quality issue.

Documentation management tools have to support documentation team in this process and provide efficient ways to automate this process. It needs to be ensured that all software UI components are assigned with the contextual help IDs and these IDs are linked to help content.

Contextual help mapping strategies

As there is a need for mapping between software UI elements and documentation contexts, let’s take a look on how this is actually done in Eclipse Help.

In most of the cases, two alternative strategies of ID mapping are used. These are:

1. Direct mapping. When context IDs of help content are placed “AS IS” in software code. This is the easiest approach, but it has a set of disadvantages e.g. this approach requires a lot of discipline in the issue of ID generation and mapping. In most of the cases, one of the teams (software development or documentation) will own the responsibility to generate unique IDs and to assign them. The other team will need to map those. This approach creates a lot of organizational overhead and does not provide needed flexibility.
2. Indirect mapping. In this approach, the software development and documentation teams can define their own context IDs independently.  Later on, these IDs are mapped to each other using a special mapping tool. This approach makes it possible to separate the processes of software development, documentation development and documentation mapping. It provides much greater flexibility in organizational aspects. Example of this approach can be seen here (DTP Approach to Eclipse Help mapping): http://www.eclipse.org/datatools/doc/20080310_DTP_Help-Helper.pdf

Advanced support of Eclipse Help in DITAworks

As DITAworks is an Eclipse-based tool, our product team decided to address challenges described above by the release of DITAworks 1.0. One of the objectives of this release is to make creation of Eclipse Help documentation in DITA as easy as possible.

The main features that will make this possible in DITAworks are described below.

Eclipse help DITA model

To define missing semantics and data structures that are needed for Eclipse Help features, we will create a new EclipseHelp DITA model (specialization). Model in DITAworks is a container for meta information that includes various elements like DITA infotypes, transformation styles, templates, editorial tools configurations and s.o.  It can be roughly compared to DITA Open Toolkit plug-in.

EclipseHelp model will include a set of specialized DITA infotypes:

• EclipseHelpPlugin - specialization of DITA map covering the specifics of Eclipse help plug-in descriptors
• EclipseHelpContext - specialization of DITA map that will be used to model context sensitive help contexts

Model will also define transformations for these infotypes, the set of visualization settings for map editor, preview templates, content validation rules and s.o.

Eclipse help model will also define an Eclipse Help project template that will make it easy for the user to start working with Eclipse Help projects.

Transformation styles will be adjusted to resolve cross plug-in links in Eclipse Help properly.

Mapping strategies in DITAworks

DITAworks will support both the strategies of ID mapping mentioned above: Direct and Indirect.

Indirect mapping strategy will be the recommended approach and it will follow the ideas described in DTP Approach to Eclipse Help mapping.

DITAworks will also provide a set of tools that will support software developers and documentation team members in the process of context ID mapping. These tools include:

1. Plugin for SW development Eclipse IDE that will support developers to generate and assign help contexts according to Indirect mapping approach. It will also detect UI elements that do not have help contexts assigned and then propose to generate context IDs for them.
2. Set of Import/Export actions that will enable the exchange of context IDs between software development and documentation teams.
3. Assignment plugin for documentation team. (out of scope for release 1.0)  It will provide the visual support in indirect assignment of generated UI context IDs to documentation context IDs. It will be possible to deploy this plugin directly into the documented Eclipse software and perform the assignment by browsing the documented UI and checking out available help content for it. In the case where content is not assigned, plugin will offer a set of available context IDs for the assignment or a possibility to add “TODO” for future.

Documentation process in DITAworks

To address the challenges described in “Eclipse Help and documentation process” section, DITAworks will support indirect mapping approach “out-of-the-box” when the development and documentation teams are working independently.

In the diagram below, we can see a sequence of actions that need to be performed for one documentation cycle/iteration:

The documentation process can start in parallel with the developers’ coding software components. The developers will use the plugins described in the previous section to automatically generate and assign context IDs to user interface elements. These IDs will be later used by the documentation team for assignment.

In the next step, the assigned IDs will be exported from IDE into the special mapping file and will be passed on to the documentation team (import to DITAworks). This is one of the possible ways to hand over the context IDs. Some alternatives can also be considered like the direct extraction of IDs from source code and s.o.

Next, documentation team documents software elements not documented yet and then maps already documented parts to incoming IDs. This mapping could be done directly in DITAworks or by using the special Assignment plugin.

Optionally, the assigned IDs can be back-synced to the Developer IDE.

In the last step, DITAworks generates a set of Eclipse help plugins from DITA source and ID mapping information. Eclipse help plugins are split into content plugins and context plugins. The content plugins contain topics and TOCs and the context plugins contain context assignments.

In the next development iteration, this process can start from the beginning with only difference being that the imported IDs will extend already existing IDs and documentation team will need to document only the newly added UI elements.

Roadmap will be regularly updated.

Specialization opens a new dimension for customizing DITA to needs of different enterprises. But doing a valid specialization is not a trivial process. It requires rather deep understanding of DITA internals and command in technologies like DTD, XML Schema and s.o.

But even with sufficient knowledge of DTD (or XML Schema) coding, doing a valid specialization requires knowledge of certain DITA principles and rules. Just designing a valid DTD will not necessarily mean that you have a valid DITA model. More on Specializations can be read here: http://docs.oasis-open.org/dita/v1.0/archspec/ditaspecialization.html

This article discusses some common problems and pitfalls people face when they do DITA 1.1 specializations .

Problem 1: Doing changes in original DITA model

One of the foremost and simplest mistakes people do with DITA is to change original DITA DTDs directly in DITA source files.

From point of view of DTD syntax or XML editing software, they do nothing wrong: DTD is parsed by editor without errors and XML is edited and validated. But real problem is that resulting DTD and contents authored according to it are not DITA any more. These new contents take a new custom format which has nothing to do with DITA.

Solution

Use DITA specialization as the only valid way of extending DITA models. It assumes that all extensions are kept in separate files and no changes to original DITA DTDs or XML Schemas are done.

Problem 2: Usage of same infotype or element names as in base DITA

Next problem that we find in specialized models is a problem related to naming of newly defined topic types (infotypes) or elements. To be more precise, naming of your new elements or infotypes becomes a problem when you give them the same name as is already being used in basic DITA model.

Due to technical specifications of DITA specialization approach, it is not possible to use the same names for new infotypes or elements that are already defined in base DITA model or other models being used. This will result in conflict during name resolution and can lead to unpredictable results on the stage of DTD parsing and transformation.

Solution

Give unique names to your new infotypes and elements. It is a good strategy to choose some kind of prefix for the names of your specialized elements. In this way, you will most probably avoid naming conflicts with other models and also distinguish standard DITA elements easily from specialized elements later on when the content is being authored.

Problem 3: Structural elements without parent

Often people are tempted to define new structural elements in DITA that have no reference to parent DITA elements. This is not a valid way according to DITA specialization.

An important part of DITA lies in the concept of generalization. According to it, any specialized model (infotype) can be automatically translated into valid infotype from base DITA model. This provides benefits of easier data interchange between organizations even if they use their own specialized models.

But benefits do not always come without costs as we know. Here, generalization comes at the cost of several rules that a valid DITA specialization needs to follow. E.g.:

1. Every XML element in specialized model has to have “parent” element reference. This reference shows which element from base DITA (or other) model was used as a “base” for specialization. This parent element will be used later on during generalization process as base representation of specialized element.
2. Content model of specialized element has to be equal or more restrictive to its parent element.

The problem, which we are talking about in this section, is violating the rule 1. Elements created in such a way are “floating” without a connection to a base DITA model and for such elements, generalization will not be possible. Transformation of these elements using Open Toolkit will lead to unpredictable results (in most of the cases, Open toolkit will highlight such elements by yellow background, thereby signaling that it was not able to find proper transformation style sheet for this element).

Solution

Select a possible parent element from DITA or other valid DITA specialization and define parent reference using class attribute.

Problem 4: Wrong element content model

Very often, people violate rule (2) from the previous section (Refer Problem 3 above): Content model of specialized element has to be equal or more restrictive to its parent element. This rule more elaborately means that the content model of specialized elements has to follow these factors:

• The content model of specialized elements should consist of elements from parent content model or their specializations.
• Multiplicity of elements in specialized content model should be the same or more restrictive as the parent content model.
• Sequence is also important.

This means that when doing structural specialization, selection of the parent element should be done with care. It is so because finally it will influence possible content model of your specialized element substantially.

Violation of this rule also makes DITA generalization impossible and as a result, the whole model cannot be treated as DITA model any more.

Though violations of this rule are very often, they are very hard to detect manually. And that is so because content models of parent and specialized elements need to be compared by taking into account the specialization of involved elements. Special validation tools (see below) can be used for that.

Solution

The solution of this problem is not always trivial and it depends on requirements towards the objective of specialized elements. There are basically 3 possible solutions:

• Adjust content model of specialized element.
• Choose other parent element.
• Combination of both above. This is the most probable scenario.

Problem 5: Mixing domain and structural elements

Another problem, that is very hard to detect manually, is related to a mix of structural and domain elements in your structural specializations.

As it is described here, it conflicts with DITA concept of separate specialization of infotypes and domains. Here is a quote:

«When you define new types of topics or domain elements, remember that the hierarchies for topic specialization and domain specialization must be distinct. A specialized topic cannot use a domain element in a content model. Similarly, a domain element can specialize only from an element in the base topic or in another domain. That is, a topic and domain cannot have dependencies. To combine topics and domains, use a shell DTD.»

The principal function of a domain is the extension of structure inline elements. These elements cannot be used directly in content models of the specialized elements.

This requirement will be relaxed in future with the release of DITA 1.2. Then, it will be easier to use elements from domains in structural specialization.

Solution

The solution of this problem can be seen in clear separation of domain and structural elements. To specialize domain elements, new domains have to be defined and linked on the level of shell DTDs.

Conclusions and a bit of self-marketing

As we can see from problems listed above, DITA specialization in current form is a process that requires a lot of technical expertise and discipline. This has hindered DITA adoption in enterprises and has established unfavorable public image of DITA being a “very complex” standard.

In a comprehensive article “10 DITA Lessons Learned…” on ContentWrangler (http://thecontentwrangler.com/article/10_dita_lessons_learned/), we read the following about specialization:

“Specialization is one of the best things about DITA, but it is also the least understood…”

and one of the main conclusions of the author is:

“Resist the Temptation to Specialize”.

From the same article, we also read:

“Specialization requires a lot of discipline. Until we have specialization wizards to help us correctly implement DTD changes that are needed when you specialize DITA, we will continue struggling to conceptualize what specialization is and how it works.”

We totally agree with this last statement. Majority of these problems could be addressed by modeling tools that should help information architects to focus on task of data modeling instead of spending time on looking for errors in their specializations. These tools should also lower entry barriers for people interested in adoption of DITA.

That’s where we see the main benefit of DITAworks modeling module. It’s the first solution in the market which provides much needed support to Information Architects in designing their DITA specializations by providing wizard-based visual editors for DITA information types. It is also able to import existing models from DTD or XML Schema and detect possible problems. Later, this model can be exported again to DTD or Schema.

We hope this is the right way to break the “Resist the Temptation to Specialize” attitude. Working with DITA specialization in tools like DITAworks can become much more agile.

Note

Problem list presented in this article was compiled from the results of validation and analysis of several DITA specializations from real customer projects. For model validation and analysis, DITAworks modeling module was used.

This list can’t be treated as a full catalog of possible problems with DITA specialization. If you have experienced other types of problems with specialization, we encourage you to contribute and share your experience in comments.

Looking forward to hear from you..