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: Re: [dita-adoption] Short descrption, 2nd review

I agree with Bob. While I have not read the paper all the way through, I see some glaring problems.

In addition to the markup and problematic short descriptions, the paper contradicts the spec. The section "How and Where Short Descriptions Appear" states that "Depending on the output type and setup, short descriptions may or may not appear above body content within a topic." It then suggests that short descriptions are not rendered in PDF output. While implementations might build their PDF style sheets so that short descriptions are not rendered, this is not the rendering expectation that is outlined in the DITA specification.

See the DITA spec at http://docs.oasis-open.org/dita/dita/v1.3/cos02/part1-base/langRef/base/shortdesc.html#shortdesc

It clearly makes a normative statement about short descriptions: "The content of the <shortdesc> element SHOULD be rendered as the initial paragraph of the topic."


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

On 1/4/2016 12:43 AM, Bob Thomas wrote:
I spent a couple of hours reviewing the latest draft. I didn't finish, but I have attached what I have done so far.

While the paper has improved, I don't believe that it is ready to publish. It still contains technical inaccuracies, and I am concerned that our audience will find it unclear in places. The DITA source markup also needs some refactoring.

Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype
Time zone: Mountain (GMT-7)

To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:

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