OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [dita] Notes on the DITA 1.3 A-Z article


My rather long notes. I like the overall paper, the theme, the style, etc. These notes are mostly editorial/stylistic niggles, but there are 3 factual errors that I think definitely need correction. I've flagged those with "IMPORTANT" here. Chris's "conrefkey" also falls in that category.

mag

==========================================================================================
Document title: It looks funny to me to have "DITA 1.3" there twice. Could this just be "Feature Article: DITA 1.3 from A-Z"? Or are we bound by some template that requires the initial phrase? If that's the case, then how about "DITA 1.3 Feature Article: What's New from A-Z"? 

--------------

Introduction, para 2 
"Similarly, an Information Architect can ..."
- I don't think this is really a "similar". It's more of a "furthermore" I think. Or maybe an "additionally".

para 3:
- This is the crux. I'd suggest trading places with para 2.

--------------

Cascade Attribute, para 1:
"In DITA 1.2, metadata values were always additive by default. For example, if you added metadata values to the audience
for a map (platform="Windows MacOS") and then add a separate targeted topicref to that map containing
audience="Linux", the latter value would automatically be added to the other metadata values for that map."
- There's an "add" in there that should be "added".
- IMPORTANT-- The very last word of the sentence should be "topic" not "map".

General comment: I always find examples of conditional attributes confusing and misleading when they are not given within the context of some corresponding publishing conditions. Is this just me? Is there a commonly assumed convention about what it means when no such publishing conditions are mentioned?

--------------

deliveryTarget (Goodbye print, Hello deliveryTarget):
- The title of this section suggests to me that attention has been paid to the catchy alphabetical nature of the paper title, ensuring that at least the document started out with A,B,C and D. (Otherwise I think the parenthetical portion alone would have been a better title for the section.) 

This title also feels (nicely) light to me (or to be precise, the parenthetical part by itself does). Another title that has a glimmer of this light tone is the "turning things around" one about the table attributes.

This makes me feel even stronger that it would be nice if the final "miscellaneous other stuff" section in the document had a title starting with Z. A couple of days ago I suggested "Zillions of other updates to DITA elements and attributes", which was countered by JoAnn with the thought that this might put off folks who think DITA is too large. But I don't think that this is likely to happen, and furthermore I think that the use of a slangy word like this would add another touch of that lightness.

And if it is felt that the lightness itself is inappropriate, then I think these other two titles I've mentioned need reconsideration for that.

--------------

Grouping Things Using div
- Typo: "In DITA its primarily purpose ..."

--------------

Highlight Domain
- FWIW in mathematics, the overline is used much more commonly nowadays for negation than it is for grouping.

--------------

Inline Elements for Describing Markup Language
"wrap a pair of <xmlelement> elements around it":
- IMPORTANT-- Not right; you are either wrapping AN <xmlelement> element around it, or you are wrapping a pair of <xmlelement> TAGS around it.

--------------

Learning and Training Specialization
This description seems really short in comparison to what my spidey sense tells me is the significance of the update from the POV of L&T people. How do L&T people feel about it? Does it need more verbiage to convey the significance, or does this do it?

--------------

Release Management
"Summary information on significant product additions or changes to a product can now be added to the prolog of
a topic or within the topicmeta of a map using the release management elements as they are being written."

- suggest rewrite to move the phrase "as they are being written" into the general vicinity of what I think is the antecedent of "they" (and to fix s/v agreement) -- all of this assuming that I am, in fact, correctly understanding the intent:

"Summary information on significant product additions or changes to a product can now be added as it is being written to the prolog of a topic or within the topicmeta of a map using the release management elements."

--------------

Same Topic References

- "Same-topic" (in the title) should be hyphenated as a compound modifier; and then the 't' should not be capitalized (although that part may be debatable).

- Not likely that your written link text would actually say "figure 1" in reality.

--------------

Troubleshooting Note Type

- IMPORTANT--  Multiple confusion here. First, the opening sentence refers to the "new type attribute @trouble". It's 'type' that should be @-ified, not 'trouble', because @type is the attribute. "trouble" is the new VALUE that we have defined for it. Then later the code sample correctly has "type" as the attribute, but has the wrong value "troubleshooting" (should be "trouble").

--------------

Troubleshooting Topic

para 1: instead of "excluding elements common to other topic types" it might be clearer to say "in addition to elements common to other topic types"

para 2 (after list): "is designed to do provide" 

==========================================================================================




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]