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

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-adoption message

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


Subject: Review of the "DITA 1.3: A to Z article"


I agree with the comments that Chris Nitchie and Tom Magliery provided to the DITA TC mailing list

Overall, I think this is a good and welcome article. There are some technical inaccuracies that should be fixed before it is released for general use. I'll split my comments into two categories below: "Things that need to be fixed" and "General comments".

Things that need to be fixed
  1. The date on the cover and footer does not match the date of the latest revision in the Document History.
  2. deliveryTarget:
    1. Change "information architects can use subjectScheme attributes to control @deliveryTarget values" to "information architects can use subjectScheme maps to control the values for the @deliveryTarget attribute."
    2. Change "it allows information architects to preprocess content targeted for specific output types" to "it allows information architects to target content for specific output types."
  3. Filtering Attributes Can Now Be Grouped: The content here is quite off. It's always (DITA 1.0 and forward) been possible to have audience="administrator programmer"; that's NOT new in DITA 1.3. I suggest conferring with Robert Anderson to clarify the use cases for grouping filtering attributes -- that's what is new in 1.3 -- it's not simple and will be difficult to explain for a non-technical audience.
  4. Learning and Training Specialization: The statement "In DITA 1.2, writer were restricted to creating a single paragraph for question-and-answer exchanges" is misleading. Yes, it was a single element specialized from <p>. But the problem was that it allowed ONLY phrase-level content -- no figures, lists, tables, etc. For 1.3, the new element is specialized from <div> and so allows everything that can be contained within <div>: multiple paragraphs, lists, figures, etc.
General comments
  • Suggest that the title simply be changed to "DITA 1.3 from A-Z"
  • Suggest adding a revision to the Document History: "Edits based on feedback from the OASIS DITA Technical Committee."
  • The TOC uses "init-style capitalization," but there are a few noticeable exceptions: "Key scope," "Sorting element," and "Table element."
  • Branch Filtering: The statement "[<ditavalref>] can operate at multiple levels with more than one behaviour" is unclear.
  • The term "information architects is capitalized in some places and not in others. Pick one convention and stick with it.

I did no have time to go through the entire article.

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)



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