Public Comment

[comment-form@oasis-open.org]

Comment from: nigel_hopper@uk.ibm.com

Comments from three reviewers that are unedited, by me.

Reviewer One:

Architectural Specification
- Page 7. Implies that DITA is defined in DTD and Schema. Which of the two is normative (my choice would be Schema if only because it's more readable than DTD)?
- Page 9. "Topic modules". This is commentary on the DTDs. The spec should either be complete in itself, or the DTD should be self documenting. Same comment applies to other similar topics in this document (especially page 35. "Modularization and integration of design"). 
- Page 9. "Topic modules". States that tables are based on the CALS model. But page 141 of the Language Specification document states that "the DITA table is based on the OASIS Exchange Table model". Are these the same thing, and if not, which is correct?
- Page 25. "Flagging logic".  The spec doesn't state the purpose of flagging (i.e. that it is intended to highlight elements in the output). Multiple flagging as described works when images are used, but not when coloured or bold text is used, and there should be a statement of the rule in that case. 
The rule for combined filtering and flagging is not stated correctly: Filtering is applied first, and if the element is included, then flagging is applied.
- General comment. There are many references to XHTML and PDF output in the Language Specification. If DITA is really bound to these output types, we should say so. I suspect that it is not, in which case all these references should be less specific. Maybe the spec should characterise them both without mentioning them by name! 

Language Specification
- General comment. The specification gives considerable detail on all the elements, but doesn't describe the relationship between them. For example, what are the containing and contained elements? We shouldn't rely on the DTD or Schema as the only specification of this sort of detail.
- General comment. The elements used in maps should be separated from those used in topics. In theory, you could use DITA topics without maps and vice versa.
- alt element. This (and several others) refers to things that are deprecated. We shouldn't deprecate things in draft 1, we should remove them.
- anchor element and elsewhere. "It is currently supported by Eclipse output only". We shouldn't bind the spec to a specific output that is supported in a specific implementation.
- author element and elsewhere. "The currently unsupported keyref attribute ...". If it's not part of the spec but will be in future, then it should say "reserved for future use" and nothing else. If it's just that a particular implementation (i.e. IBM's) does not support it, it should be specified in full. The present wording exposes the spec to different interpretation by different implementers.
- coords element. "Pixels are recommended ..." and following note. This is implementation detail which should be removed.
- draft-comment element. "Note: ..".  This is placing an obligation on the processing system. There are other obligations expressed elsewhere. There should be a statement in the Architectural Specification that makes it clear that while some details are up to the implementation, there are certain things that processing systems must do.
- example element. Remove the comparison with IBMIDDOC.
- fig element. "Sometimes called an 'exhibit' ". Delete this, as it doesn't add value.
- fig element. "A title is placed...". Delete this sentence - it is redundant.
- i element. " .. this may vary ...". If this is a typographic element, italic should mean italic. I understand why other elements are not  tightly coupled to the presentation, but this (and b and u) should be.
- image element. "always include a description of the image's content in the alt attribute". But when we describe the alt element we state that the alt attribute is deprecated. In any case, this is more a direction to the user than a specification.
- indextermref element. If this is not currently supported, and might be deprecated in the future, should it be included at all?
- keyword element. Last paragraph is implementation detail that doesn't belong in the spec.
- li element. The important point is not that output is displayed with number and alpha in the one case and bullets in the other, but that the list is presented in a way that indicates that the sequence is (or is not) important.
- lines element. Description should be independent of the description of the pre element.
- map element. Delete the description of Eclipse requirement as it's not part of the DITA spec.
- mapref element is missing - as this is planned for future and provides an elegant way of imbedding maps within maps, it should be included.
- note element. The type attribute says that othertype needs a stylesheet otherwise the note is ignored. This is not true for the IDWB, so why should it be the case for other implementations?
- othermeta element. " .. and have no defined meaning for other possible outputs such as PDF."  Who knows what PDF might support in the future, or what future output there might be. 
- pre element. ".. and also presents the content in a monospaced type font (depending on your output formatting processor)". Monospace output should be mandatory (see my comment for the i element).
- related-links element. Processing note 1. This should be for the processor implementation to decide.
- required-cleanup element. The note is a good example of how the processing requirements should be expressed. But we need a definition of a DITA processor in the Architectural specification.
- screen element. The example output in its present form really undersells the value of this element. I suspect that the screen element may not have been used to produce it.
- shape element. Delete the reference to the failings of the various browsers.
- shortdesc element. The second sentence is really the crucial point of shortdesc. The spec should spell out the obligations for DITA processors.
- table element. Note on the scale attribute. The reference to "legacy purposes" isn't appropriate. This attribute should be supported or deprecated. " .. use the scale attribute judiciously ..." should be replaced with specific advice.
- term element. "In future development of DITA ...". There should be some indication of how this might work, and any attributes that are needed should be reserved. Otherwise, we will find that someone implements this in a way that conflicts with the intended processing.
- tm element. "In your company's documents ..". The spec should describe what the DITA processing is obliged to do with the element.
- tt element. This is a poor choice of name for this element. Although the venerable Teletype is worth commemorating, this is not the place to do it. Use a name which says what it does - I suggest monospace.
- tutorialinfo element. "This information is currently included ...". Only if the processor elects to do so. 
"It is not for use in tasks that are being used outside of tutorials". This statement doesn't tally with the concept of reusable topics. A task doesn't "know" where it is being used. Which means that authors will have to provide two copies of the topic - one containing the tutorialinfo elements, and one with the elements excluded.
- var element. "It is represented in output in italic font". This depends upon the output processors, and the user's style rules.

- outputclass attribute on all elements. Refers to CSS processing. Does DITA support the use of XSL for stylesheets?

- %display-atts; and elsewhere. Refers to the contents of the DTD. But we state in the Architectural Specification that DITA can be specified in Schema as well. These topics should specify the attributes independently of the whether Schema or DTD is used.
- %display-atts; "In DITA tables, in place of the expanse, ...". Why use two different attributes to denote the same thing? And I suggest using meaningful values rather than 1 and 0.

Reviewer Two

One small detail I noticed - in the architecture specification on pages 24 and 25 (the processed version of p24's example) there's the phrase

<li platform="Windows">Do a special thing for Windows</li> 

I don't see a trademark attribution of any kind. Is this a potential concern? I don't know if MS have any involvement with the OASIS group, but I might suggest substituting "Linux" as more suitable in this context.

Also, I notice that there's no explanation of why the name "Darwin Information Typing Architecture" was chosen. I think it is worth adding some explanation of this (invented if necessary... do we have an IBM site in Darwin, Aus.?).

It is not correct to assume that associating something with Darwinism (which is the default if no explanation is given) will have the effect for all readers of increasing its approval rating or conveying the meanings of "scientific, clever", especially in the USA. My feeling, based on both my personal standpoint and my reading around this issue, is that this association has the potential to make some readers uncomfortable, or to make some readers interpret it as a statement of positioning or worldview. I think to help avoid any association with what is a known issue of controversy, an explicit explanation should be given of why this name was chosen.

Reviewer Three

I believe the 'purity' of DITA is not as clear as it should or could be. The use of <b> and <i> elements is clearly indicating the style that the content should be displayed as rather than perhaps using <strong> and <emphasis>. The committee has the opportunity to correct this in release 1 of the specification. While it might be seen that there is little semantic difference between <b> and <strong>, the temptation could be that as there is a precedent, other elements of a similar ilk could be introduced to the specification.

Attributes should not contain 'free text'. For example the navtitle attribute on the <topicref> element. The function of an attribute is to help define the quality or characteristic of the object. The navtitle in this case is an object in its own right and should become an element that is nested in the topicref element. Having attributes that contain free text places severe limitations and maintenance issues on the information in those attributes. For example, a product name would have to be manually maintained rather than being handled as a conref'd keyword.

Inability to nest <keywords>. This is just an unnecessary limitation on this element. Using the keyword element with an id and conrefing to it is effectively the methodology for handling text entities. While there are work arounds for not being able to nest them, there is a maintenance overhead that is introduced and is unnecessary. For example:

Where you are looking to create compound elements to handle such things as product name and version or product name and platform or some other variation, you will need to use individual keyword definitions for each variation. For example you will not be able to the following:

<p><keyword id="pname">DITA Product</keyword></p>
<p><keyword id="pname11x"><keyword conref="common.dita#common/pname"></keyword> 1.1</keyword></p>
<p><keyword id="instdir">C:\Program Files\IBM\<keyword conref="common.dita#common/pname11x"></keyword></keyword></p>

The first keyword element is valid, but the second and third are not as you cannot nest a keyword element within another. Although this is possible with <ph> elements, you cannot insert <ph> elements in all the locations that you will need to place a conref to the source data. The following approach can be used but means that each 'entity' would need updating in the case of a name change:

<p><keyword id="pname">DITA Product</keyword></p>
<p><keyword id="pname11x">DITA Product 1.1</keyword></p>
<p><keyword id="instdir">C:\Program Files\IBM\DITA Product</keyword></p>

Currently the prereq elements come first followed by the context elements in Task topics. This would mean that you are reading what the prerequisites of the task are, before you actually have read and understood in what context you are actually performing the task. Reversing the order of these elements (or perhaps allowing them in either order to get around the issue of those topics already written as such) would mean that you would read and (hopefully!) understand the context of the task at hand before looking at anything you might need to do.


Architectural Specification
- Page 15 of the DITA Architectural Specification. Chapter 3. Figure 1 and Figure 2 both have in the comments A linking to A1, A2, A3 as children, but unless I am mistaken, A3 does not appear in either of the examples. In the second example it looks as though "(no links to B as previous)" needs to be the third line against A2 as it is for A1.

- Page 16 as above. navtitle should ++NOT++ be an attribute. It should be an element in its own right as it is in the topic.

- Page 17 as above. In the example of a simple relationship table, in the relrow, the second and third cells are missing an opening relcell element.

- Page 20 as above. In the Identity attribute section, first bullet point, 3rd paragraph, 3rd line. There is a space missing between the web address and URIs. (Actually between the '.' at the end of the address and URIs).

- Page 21 as above. In the Content reference attribute section, please re-write paragraphs 3 and 4 (starting More formally... and If the referenced....) in to something understandable.  You have made it sound far more complex than it actually is. I have users avoiding using it, because it has been made to sound complex and yet is one of the easiest approaches to use in relation to reuse.

- page 24 as above. In the section Using metadata attributes. Is it right to refer to these attributes as metadata attributes? Are they not just 'attributes'? Same questions as for Processing metadata attributes.

- general. Better information and examples of relationship tables should be provided.


Language Specification
- b element. Should not be in DITA. Should be a <strong> element.
- boolean. If it is deprecated, remove it. This is a first release. If people are using it, then they will have to adapt to it going at some point, so why not make it the first proper release of the spec etc.?
- general comment. Try not to split example 'code' over a page. Example chdesc on page 9. The example is split on the opposite side of the same piece of paper! Would make it easier to read. 
- colspec. The colspec example on page 21 seems to have lost some of its formatting
- created. Why is the date an attribute? Not sure it makes sense. Applies to revised element as well.
- entry. I believe that the entry element would benefit from an id and conref attribute
- i element. Should not be in DITA. Should be an <emphasis> element.
- keyword. The explanation of this could be better. My understanding is that something identified as keyword only has the semantic attachment that the author wishes to give it. The current write up seems to indicate it is more than this. I would resist the temptation to use the examples in there such as name of a command or parameter as these should have (command does) elements in their own right. It implies that it might need to be in an enumerated list. The use of keyword was expanded to allow it to be used as a text entity replacement. The description gives me an indication that it has more semantic value than we have been lead to believe and this would then lead me to question its use as a text entity replacement. Of all the descriptions this one might need the most work to ensure that it does not have too much information (or too little) that takes it away from my understanding of its intended use. I've just checked with one of our US DITA tooling experts and he agrees that my understanding that it only has the semantic meaning the author wishes it to have is his as well. In fact, if used as a text entity, it can effectively have no semantic meaning and is just the mechanism for working with common information.
Suggest that "or<indexterm." is removed from the third paragraph as it is unnecessary and makes it clearer that only a keyword element in a keywords element will appear in metadata.
- keyword. Should be able to nest itself.
- ph. Says "is used to organise content for reuse...". This is not the best element for this as it cannot be nested in a number of places reusable information is required. My understanding is that this is the keyword element. Perhaps that should be updated to reflect this comment?
- propdeschd, proptypehd, propvaluehd. As this is probably written in DITA and as the information is probably common, put the relevant information in each section and save people having to turn the page to look at the attributes for property. You could even set up and id and conref for the relevant information. :-)
- repsep. No example code.
- shortdesc. Description needs enhancing so that it states where the shortdesc information appears. i.e. hoverhelp, start of a topic, short description with the topic title as a link.
- sub, sup elements. Bit like i and b elements. Should they be there or emphasis and strong versions of sub and sup?
- tt. Should be something else. Very legacy! :-)
- u. as fro b, i, sub and sup.