Review C: Comments about the "Element-by-element" recommendations for tr

Thanks to Dawn and Eliot for giving this topic a close reading. Here is a high-level overview of their comments (and my take on them):

Information design of the tables needs a rework. Because the same design is used for almost all tables, there are columns that are not applicable or do not contain any content.
The headers for the columns are not explained clearly; they are confusing and unclear.
The table cells contain formatting – bold highlighting and upper-case letters that is inconsistent AND not explained clearly.
It’s unclear WHY these tables even need to have a column about whether an element typically in rendered as a block or inline element when presented to a reader.
“Subflow” is not clearly explained.
The value of “block (metadata)” in the “Topic elements” table is confusing. Also, the inconsistent values of “n/a”, “n/a (metadata), and “n/a (empty)” throughout are confusing.

I’ve done one pass through reworking the content and information design, and will attach a PDF.

More substantive comments – From Eliot, in regard to <image> and <hazardsymbol> (specialized from image):

“How is @othertype translatable? It would normally be used as a keyword to the rendering to then generate the appropriate label, which would be localized in the rendition processing. Expecting authors to provide the presentation label in @othertype would be very bad practice.”

Best,

Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com

Skype: kriseberlein; voice: +1 (919) 622-1501

dita message