I wholeheartedly agree: promoting effective use of short descriptions is the whole point of the article.
But I think we would be remiss if we didn't state that in some (misguided) circumstances it has been turned "off" in some production environments--I have seen that with a couple of clients I have worked with. If that's the case, we need to explain why this
is not the recommended behaviour and provide the reader with good reasons for wanting to turn the visibility of short descriptions back "on" at output.
Stan sent me an email off-list that talked about some of the reasons he's seen for not using short descriptions. I will include some of those points in the next re-draft in order to rebut them.
Cheers!
Keith Schengili-Roberts
DITA Information Architect / DITA Specialist
IXIASOFT
825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1
tel + 1 514 279-4942 / toll free + 1 877 279-4942
cell + 1 647-472-7367
From: dita-adoption@lists.oasis-open.org <dita-adoption@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com>
Sent: Monday, January 4, 2016 1:26 PM
To: Hackos, Joann; dita-adoption@lists.oasis-open.org
Subject: Re: [dita-adoption] Short descrption, 2nd review
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
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
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
|