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 suggested the rationale in this blog piece to the group as reasons why groups that eschew the use of shortdesc may be selling themselves short. http://ditaperday.com/blog/the-shortdesc-element/

In general, "Shun shortdesc, risk being shortshrifted in function." Some particular data specializations may not require the annotative function of shortdesc normally had in OT processing, so I can't say "no" in all cases. I would, however, point out that even data specializations without annotation are half-complete. It is the header to a payload in transaction packets; the reason for using the particular API call; the "why you should really read this" to the possible outcomes of miswiring the fuse to an atomic bomb; the heads up to whatever should be of concern or interest to you.
--
Don

On 1/4/2016 12:26 PM, Kristen James Eberlein wrote:
I think that modifying style sheets to NOT render short descriptions is misguided and a poor practice that the Adoption TC should not encourage.

Best,
Kris

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

On 1/4/2016 12:00 PM, Hackos, Joann wrote:
Actually, I just reread that part of the short description feature article and I don’t think it implies at all that the short description should not appear. It simply says that many stylesheets are designed to eliminate the short description. It could be a bit more explicit but it doesn’t contradict the spec.
JoAnn

JoAnn T. Hackos, PhD
President
Comtech Services Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
303-232-7586

 

Comtech Logo 2005 small


Join The Center for Information-Development Management Online Conference – Measuring Anything 2016 on January 26-27. More information at: https://forum.infomanagementcenter.com


From: Kristen Eberlein <kris@eberleinconsulting.com>
Date: Monday, January 4, 2016 at 2:47 AM
To: DITA Adoption TC <dita-adoption@lists.oasis-open.org>
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."

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+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.

Regards,
--
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:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

--------------------------------------------------------------------- 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: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php


This email has been sent from a virus-free computer protected by Avast.
www.avast.com


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