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] Fwd: Re: [dita] Adoption Committee whitepapers


I cannot figure out what you are all saying. You believe that short descriptions belong in he topics, not just the ones that are in this article? Is that the conclusion because you don't like these short descriptions? 

Please look at the correct draft before making any more comments about the old draft.
JoAnn

Sent from my iPad
JoAnn Hackos
President
Comtech Services Inc
710 Kipling Street Suite 400
Lakewood CO 80215
303-232-7586

 

Join The Center for Information-Development Management at the Content Management Strategies/DITA North America Conference on April 4-6, 2016. More information at:https://cm-strategies.com


On Feb 29, 2016, at 8:24 AM, Bob Thomas <bob.thomas@tagsmiths.com> wrote:

Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity.

Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago.

I also agree with Nancy's comments.

Best Regards,
Bob Thomas

On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison <nharrison@infobridge-solutions.com> wrote:
Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF). 

It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ("How and When Shortdescs appear")  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as "What do you use a Shortdesc for?"  Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context.

And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either...


There's a lot of good information in the article, but I do think it needs a bit more work.

Nancy


_____________
Nancy Harrison
Infobridge Solutions 
nharrison@infobridge-solutions.com

On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:
Just to make sure that the Adoption TC saw this also.

Best,
Kris

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



-------- Forwarded Message --------
Subject: Re: [dita] Adoption Committee whitepapers
Date: Tue, 22 Dec 2015 08:19:40 -0500
From: Kristen James Eberlein <kris@eberleinconsulting.com>
To: dita@lists.oasis-open.org


The PDF is ... a little bizarre.

The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example:

Good Short Descriptions = Better Search Engine Results for Online Documents
Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine
Optimization (SEO).

Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that
the information it seeks is in your document. When a short description is absent, by default the first sentence or two
appears in its place, which rarely summarizes what the content of a topic is about.

Conclusion
Summing up why short descriptions are a good idea.

Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators
alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and
can help content creators decide which topic is appropriate for reuse.

I don't think this is ready for prime time.

Best,
Kris

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

On 12/21/2015 8:41 PM, Bob Thomas wrote:
Hi,

The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it.

A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review.

Best Regards,
--
Bob Thomas
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




--
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)




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