Here's a crazy thought: has anyone thought about approaching the people who manage CommonMark Markdown about the possibility of *them* adding shortdesc to their spec?
I'd be happy to make the case on
https://talk.commonmark.org/ to see what they say...
Cheers!
Sent: Tuesday, February 7, 2017 2:07:16 PM
To: Storbeck, Joe; Carlos Evia; dita-lightweight-dita@lists.oasis-open.org
Subject: Re: [dita-lightweight-dita] Short descriptions in LwDITA
Thanks and best regards,
--Scott
Scott Hudson
Content Strategist
Digital Aviation Learning & Development
Voting member:
OASIS DocBook TC, Publishers SC
OASIS DITA TC, Tech Comm SC, LW DITA SC, Learning Content SC
OASIS Augmented Reality in Information Products (ARIP) TC
Jeppesen | Digital Aviation | Boeing
55 Inverness Drive East | Englewood, CO 80112 | www.jeppesen.com
Date: Tuesday, February 7, 2017 at 12:00 PM
To: Carlos Evia <cevia@vt.edu>, "dita-lightweight-dita@lists.oasis-open.org" <dita-lightweight-dita@lists.oasis-open.org>
Subject: RE: [dita-lightweight-dita] Short descriptions in LwDITA
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:jstorbeck@janacorp.com
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:
dita-lightweight-dita@lists.oasis-open.org [mailto:dita-lightweight-dita@lists.oasis-open.org]
On Behalf Of Carlos Evia
Sent: Tuesday, February 07, 2017 12:46 PM
To: dita-lightweight-dita@lists.oasis-open.org
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