Re: [dita-adoption] Short descrption, 2nd review

[Kristen James Eberlein <kris@eberleinconsulting.com>]

I am good with what you suggest. I really, really just did not want an Adoption TC article to encourage (or even condone) building transformations to not render short descriptions.

On the other hand, I have done some interesting work with some clients around specializing abstract and shortdesc for more complicated transformations ...

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 2:14 PM, Keith Schengili-Roberts wrote:

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 

robertsk@ixiasoft.com / www.ixiasoft.com

 

---

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

Joann.hackos@comtech-serv.com

303-232-7586

 

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