Just to be sure --- Please put me in the the camp of the content of
the shortdesc SHOULD be rendered in the output, per the normative
statement in the spec:
The content of the <shortdesc>
element SHOULD be rendered as the
initial paragraph of the topic.
http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/base/shortdesc.html#shortdesc
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
On 2/29/2016 11:20 AM, Don Day wrote:
As another long-timer with the design, I've also understood and
taught the use of the shortdesc as a first paragraph in all
instances, with special behaviors. I don't care if my credit card
quote is used; in the blog post where I first used the allusion,
it was meant to imply a loyalty program--if you use it
consistently, you reap rewards throughout the life cycle of your
topics. Let it go if it doesn't fit. Still, my own recommendation
is always to use it since any lesser recommendation encourages
some to not use it, with potentially very costly rework down the
road once the "rewards of membership" do start to become apparent.
That is all.
--
Don
On 2/29/2016 9:46 AM, Michael
Priestley wrote:
Hi Bob,
I think shortdescs are normally
rendered in PDF, as well as HTML.
For what it's worth the design
intent for shortdescs at the time of their addition to the
language was to implement the "thesis sentence" principle of
the STOP methodology, where the first sentence of a topic
provides its thesis/key point. This "thesis sentence" is then
also useful as a search result preview etc. but its first and
primary purpose is to be the first sentence of the topic.
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/michael-priestley
From: Bob Thomas <bob.thomas@tagsmiths.com>
To: Nancy Harrison <nharrison@infobridge-solutions.com>
Cc: Kristen James Eberlein <kris@eberleinconsulting.com>,
"dita-adoption@lists.oasis-open.org"
<dita-adoption@lists.oasis-open.org>
Date: 02/29/2016 10:24 AM
Subject:
Re: [dita-adoption]
Fwd: Re: [dita] Adoption Committee whitepapers
Sent by:
<dita-adoption@lists.oasis-open.org>
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 --------
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
+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
--
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)
--
"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot
This email has been sent
from a virus-free computer protected by Avast.
www.avast.com
|
|