Re: [dita] Comments about DITA A-Z article

[Eliot Kimber <ekimber@contrext.com>]

I've reviewed the paper and provided my comments to Keith directly.

I agree with all the comments posted by others. I mostly either struck out
things that didn't need to be there at all or suggested rewording of
existing statements to make them more technically accurate.

My major comments were:

Accessibility:

The accessibility issue is really knowing what cell serves as the column
or row header for a given cell, which is not quite the same as knowing
which column a cell belongs to.

A better wording might be "not be easy to keep track of what the column or
row headings are for cells in the table. When the heading cell is not the
column heading or first column in a row, table authors must indicate which
cells serve as the headers for the cell."


Cascade Attribute, first para:

This is worded backwards--it implies that the topicref contributes to the
map's metadata, but it's the other way around: the effective value of the
topicref's metadata includes the values inherited from the map. Need to
reword to make that clearer.


Learning and Training:

Replace first para with:

In DITA 1.2, writers were restricted to phrase-level elements in the
question statements, answer options, and feedback components of questions
(interactions). For DITA 1.3 the new learning2 domain allows paragraphs
and other block elements in question statements, answer options, and
feedback.


MathML and SVG:

Last para--delete. My comment is:

This isn't really a useful statement. The inclusion of MathML and SVG in
the grammar won't change the implementation status of tools and certainly
doesn't result in any *automatic* ability for tools to handle these
formats if they couldn't before.


Release Management:

In first para, replace last part with:

markup needed to capture accurate release notes in maps and topics. [WEK:
the domain doesn't provide any tools or guarantee any ability to *produce*
the notes.]


Last para: delete

This statement is true (or not true) for all new DITA 1.3 markup. The only
difference with the release notes is that the default fallback behavior is
to not reflect it in the output.  It occurs to me know that we need to add
support for release notes to the DITA 1.3 OT 1.x support plugin. I'll
create an issue for that.

Other Updates:

3rd bullet: doesn't make any sense as written. Either delete or replace
with something that does make sense. Not sure what actual feature change
it's trying to reflect.

Cheers,

Eliot

----
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com




On 8/26/15, 10:04 AM, "Robert D Anderson" <dita@lists.oasis-open.org on
behalf of robander@us.ibm.com> wrote:

>Overall, as with Tom, I like the tone and it seems to catch all the
>updates. I've noted some factual errors that should be corrected /
>clarified, along with a couple of typos that should probably be fixed.
>
>Accessibility markup for tables
>This one worries me - I think it's very misleading. It implies that
>tables in DITA prior to 1.3 are not or cannot be accessible. That's
>simply not true. For example, with the table described, properly marked
>up tables using DITA 1.0 markup, such as <thead>, can generate perfectly
>accessible output for screen readers. DITA-OT has done so since day one;
>this was in fact a pre-requisite for the HTML to be used by IBM, so
>support was there in DITA-OT 1.0. The new markup is necessary only in the
>following situations:
>* Use of tools that do not create accessible tables based on existing
>markup - authors can now maintain that by hand.
>* Tables with unusual headers, such as a single header cell in the middle
>of the table, or a header column in the middle of a table (while
>possible, I've never seen this required by any of my customers in IBM).
>
>I'm not sure how best to convey that in simple language but would be
>happy to help. I've already had to calm people who heard about this
>feature and feared they needed DITA 1.3 to produce accessible output, so
>I think it's important we don't cause more of that.
>
>Branch filtering
>Minor comment about this text: "For example, if your topics have
>information listed in metric and imperial units of measure, you can now
>easily generate tailored publications from a single map instead of having
>two separate maps or ..."
>
>As described, that can be done today (gnerate multiple publications from
>a single map). The key with branch filtering is that you can generate
>both sets of tailored information in a single publication. Maybe
>something like this?
>"For example, if your topics have information listed in metric and
>imperial units of measure, you can now easily generate tailored versions
>of the information within a single publication instead of having two
>separate maps or ..."
>
>Context-Sensitive Help
>I think there is a minor factual error in this: "Positional information
>for a particular target display can be set using the new <ux-window>
>element within the topicmeta of a map or as an attribute within a topic."
>
>Positional information can be set using <ux-window>, and then *referenced
>by* an attribute (on <resourceid>) within a topic. It cannot be set
>within the topic.
>
>deliveryTarget
>I really like the write-up, just have a couple of things:
>1. Described as a binary "yes|no" nature -- in fact there are 3
>meaningful values (with "printonly"). Not sure if this counts as a binary
>nature. Maybe better to describe as "The limited set of values (yes, no,
>or printonly) was too..."?
>2. It says @print has been replaced with @deliveryTarget. It hasn't
>actually been replaced, it's deprecated in favor of @deliveryTarget. I
>realize this document may want to avoid the technical term deprecated - I
>just don't want to give people the impression @print is gone and their
>documents must change to be valid.
>
>Also, if you wanted to add a third limitation -- @print could only be
>used at the topicref level, @deliveryTarget can be used at any level.
>
>Filtering attributes can be grouped
>This one is wrong - you can use audience="administrator programmer" with
>all versions of DITA. The new groups allow you to subset the attribute.
>One of those things I expect to be of great utility to a relatively small
>number of people. Best example I've found, and where we use it in IBM, is
>on @product -- you can group types of products that are related to your
>content. For example, something that works on top of 2 databases and 3
>different application servers would let you group those within @product --
>product="database(A B) appserver(X Y Z)"
>The purpose of the groups is to let you filter those independently. If
>you want to exclude both databases, this content can be filtered out,
>regardless of what application servers are used.
>
>This is not easy to explain in simple language (it's intended for
>advanced DITA users). Maybe it's best to explain it by saying - you can
>now mock up specialized attributes within the DITA 1.0 filtering
>attributes of audience, platform, product, and otherprops. Backwards
>compatibility restraints do not let us turn these into specialized
>attributes. When you have multiple categories of metadata that are really
>specialized types of audience (or platform or product), this lets you
>treat those categories as independent attributes while continuing to
>identify them as an audience (or platform or product).
>
>MathML and SVG
>Editing typo, should remove either "for those trying to make" or "in
>order to make": "... involved repeated trial-and-error for those trying
>to make in order to make ..."
>
>Sorting element
>Very minor thing but looks like an editing typo. Second sentence starts
>with "So a writer can...". I think this is supposed to be something like
>"A writer can now..."
>
>Other updates to Individual Elements / Attributes
>The third bullet is wrong:
>"For many elements, the attribute values @format and @scope?commonly used
>in links?use the value "ditamap" so that links now point by default to
>the map rather than to the topic."
>I think this is a reference to the new defaults for @format and @scope,
>but I'm not sure. If that's the case, a better description might be:
>"For many elements, the attribute values for @format and @scope--commonly
>used in links--can now be inferred based on the value of @href. For
>example, this means that links to a file with a ".html" extension will
>automatically be treated as links to an HTML file, without the need to
>set @format."
>
>The eighth bullet is not quite right:
>"The <prop> and <revprop> elements can now take the @style attribute, so
>text selected in a DITAVAL file can be set to bold, italics, or any other
>style property."
>The @style attribute was present when prop/revprop were defined in 1.1.
>The change in 1.2 is that you can now type in any value (or multiple
>values); previously, it was limited to a few.
>
>Robert D Anderson
>IBM Authoring Tools Development
>Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)