As a co-author of a White Paper on the importance of short descriptions ( https://www.oasis-open.org/committees/download.php/57803/DITA-Adoption_2016_Writing-Effective-Short-Descriptions.pdf ),
I strongly vote to keep the short description tag and NOT to default to the first paragraph.
Regards,
Joe
Joseph Storbeck
Senior Structured Data Analyst
1717
Universal City Blvd
Universal
City, TX 78148
Phone:
(512) 438-9457
Fax:
(210) 616-0088
e-mail:
JANA, Inc. is an Equal Opportunity Employer.
If you have received this e-mail by mistake please inform us and destroy this e-mail and any documents it might contain.
From:
[mailto:]
On Behalf Of Carlos Evia
Sent: Tuesday, February 07, 2017 12:46 PM
To:
Subject: [dita-lightweight-dita] Short descriptions in LwDITA
Dear Lightweight DITA subcommittee members,
We didn't have time in yesterday's call to talk about an issue that has been buried in the agenda for a few weeks.
As I work on the committee note and detail (used as a verb here) the list of DITA elements in LwDITA and their equivalents in XDITA, HDITA, and MDITA, I go back to the question about shortdesc and how to represent it across our authoring
formats.
In the initial MDITA draft I proposed to Michael back in... ooops... 2014??... shortdesc did not exist, and the first paragraph in a Markdown file was by default treated as a short description.
Then, Jarno asked "What if the topic only consists of one long paragraph?" and we decided to keep things simple and use "raw" HTML/HDITA in MDITA for elements that do not exist in Markdown but would be ok with CommonMark.
As a result, now a short descriptions is <p data-hd-class="shortdesc"> both in HDITA and MDITA.
Question:
- Should we go back to just treating the first paragraph in MDITA as a short description?
- If we do that, do we really need <p data-hd-class="shortdesc"> in HDITA (HTML5?)
- And do we even need that in XDITA as <shortdesc> if we are just defaulting to first paragraphs?
Best,
Carlos
--
Carlos Evia, Ph.D.
Director of Professional and Technical Writing
Associate Professor of Technical Communication
Department of English
Center for Human-Computer Interaction
Virginia Tech
Blacksburg, VA 24061-0112
(540)200-8201
