How many EDDs and templates do I need?

Report · May 12, 2014

Hello,

I'm planning to set up a documentation project using DITA (1.2) and I'm evaluating which editor would be better. The output will be PDF files (in various formats: A4, A5 and Letter for various documents: instructions for use, technical manual, etc) and the content will be translated in more than 20 languages (including Japanese, Chinese and Korean).

I saw that some consultant managed to define only one EDD for all languages but then does it mean that if I can't have one, I need one EDD per language? Then do I need one template per EDD or can I have several templates for an EDD?

Best regards,

Annette

Report · May 12, 2014

HI Annette...

This can be done in various ways. Yes, you can have one EDD for multiple templates, or multiple EDDs .. there isn't one "right" way, it really depends on what your needs are and who is maintaining the files. The EDD is imported into the template, the template is associated with a structure application. So you could have multiple applications/templates that all share the same EDD.

With DITA (1.2), using the default Adobe setup, you've got one app per topic model. This matches the structure of the original DITA DTDs and makes sense from one perspective, but is a real pain to maintain. The default structure applications provided with DITA-FMx gives you one app for all of the main topic types. This simplifies the maintenance considerably. Also, the default EDDs are built from a series of nested text insets (which also replicates the default DITA DTD model). This can be very difficult and time consuming to make sure the insets resolve properly when updating element definitions. The DITA-FMx EDD has one level of insets.

Additionally, DITA-FMx provides a feature called "component templates" which are an additional layer of templates that can be applied to different book components (chapter, part, appendix) or based on the @outputclass value of topicref elements.It also provides the ability to specify alternate templates based on the @xml:lang value of the map.

You can basically do all of this with default FM-DITA, but you'll have to do much of it manually, where DITA-FMx automates most of the publishing process (once you've got it all set up).

I hope that's useful info.

Cheers,

…scott

Scott Prentice

Leximation, Inc.

www.leximation.com

Report · May 12, 2014

Just to add briefly to Scott's comment on the text insets in the DITA 1.2 EDDs included in FrameMaker. He described updating the text insets as "time consuming". That phrase doesn't suggest just how intolerable the performance is. However, if you want to start with the provided EDDs and are only maintaining a few of them, you can convert the text insets to text. Once that is done, the performance problem disappears but without a tools such as I mentioned in an early reply, you may have to make parallel changes in multiple EDDs.

Scott also mentioned the trade-off between maintaining a different EDD for each DITA 1.2 DTD versus a single EDD for multiple topic types. The provided database.edd.fm, which is the counterpart of database.dtd, support multiple technical content topic types.

--Lynne

Report · May 12, 2014

Annette,

The number of EDDs and templates varies with project requirements and with some personal preferences of the developer. An EDD contains two types of information:

1. Definition of element and attribute types, analogous to the information in an XML DTD or schema

2. Possibly content-dependent formatting information associated with specific elements

A template contains more general formatting information such as page layouts (master pages) and catalogs of paragraph and character formats (styles) that may be applied through an EDD. Templates may also contain sample content that serves as a starting point for new documents. Some specifications can be made in either the EDD or the template and sometimes element-specific information (such as the master page to use when a particular element occurs) is made in the template.

It is certainly possible for element definitions from one EDD to be imported into multiple templates. For instance, I've worked on projects where chapters, appendices, and bibliographies have different master pages and hence use different templates, but share an EDD.

As an example of how the template and EDD interact, suppose notes are identified by a language-dependent label which in English might be "Note:". Such a label can be:

1. The autonumber of a paragraph format with a language-independent paragraph tag defined in a language-dependent template.

2. An autonumber or prefix specified in an language-dependent EDD.

3. An autonumber or prefix specified in a language-independent EDD that tests an attribute of the note element or a containing element to determine which particular autonumber or prefix to use.

When variations of a base EDD are needed to support slightly different types of documents or multiple languages, FrameMaker constructs such as variables and conditional text allow the common parts of the EDD to be reused. See http://www.txstruct.com/papers/FrameUsers00.RelatedEdd.pdf for a description of a tool that supports reusable EDDs.

--Lynne