Thanks for the thoughtful response, and see <kje> comments
below
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 1/26/2019 12:09 PM, Alan Houser
wrote:
Thanks, Kris. Dispatching the DITAweb comments was obviously a
substantial amount of effort.
Just to run a couple of items up the flagpole --
- The use case for <ph> differs substantially between
DITA and Lightweight DITA. In DITA, <ph> is clearly a
basis for specialization. OTOH, specialization is not a priority
for Lightweight DITA 1.0, and <ph> is much more likely to
be used as a generic semantic wrapper, for filtering or other
purposes (or, in both specs, as a conref container). We may want
to consider conditional processing on <shortdesc> content
between the two specs (only for <ph>), or punt on
<shortdesc> reuse between the specs for <ph>.
<kje>When we can, we need have a common short description,
and save conditional processing for the following sections: "Usage
information," "Formatting expectations," and "Processing
expectations." Elements must have the same basic meaning in DITA
2.0 and LwDITA.
I've reworked the <ph> topic as follows; I also sent e-mail
regarding it to Carlos and Deb, who were the folks who made
comments in the DITAweb review:
<ph>
A phrase is a small group of words that stand
together as a unit, typically forming a component of a clause.
- As I author topics for the LwDITA spec, I find the
"Formatting Expectations/Processing Expectations" distinction to
be more tedious than I anticipated. "Formatting" _is_
"Processing". As I write LwDITA spec content, I'm not assuming
content will be rendered as text, which further clouds the
distinction. (I expect audio and machine consumption will be
increasingly popular use cases).
<kje>This brings up a good point; we probably need to
explicitly state "For text rendering" in the "Formatting
expectations." And think more in the DITA 2.0 spec about how audio
and machine consumption should affect spec topics ...
But, as we've mentioned in TC calls, we need to look at
single-sourcing material for sections other than the short
descriptions. Processors will need to handle elements the same
way, whether in LwDITA or DITA 2.0. Obviously there might be more
processing requirements for DITA 2.0.</kje>
Looking forward to our discussion Monday and beyond.
-Alan
On 1/26/19 8:40 AM, Kristen James
Eberlein wrote:
Remember the DITAweb review that was run in October 2018?
I've spent about 20 hours this work going through the DITAweb
review, resolving what I can, and compiling a list of items
that still need resolution.
Here's a summary:
- Short descriptions: 10 topics need discussion. I've
set up a meeting for noon - 1 PM ET on Monday, 28 January
2019; ping me if you want an invitation. Currently, the
attendees will be me, Robert, Carlos, and Alan. Attached is
an HTML summary of the comments that we'll begin with.
- Examples: Lots of comments here
- We need to standardize the introductory paragraphs that
precede the code blocks. We need to decide what is the
best approach, and whether we will identify a few patterns
that can be used, or a single pattern.
- Concern that some of the examples are too US-centric or
inaccessible to ESL readers, for example, a reference to
Rotten Tomatoes and "How to purchase SuperWidgets from the
warehouse." We need to enhance our guidelines for example.
- Suggestions of multiple additional examples. We need to
review our existing guidelines for examples and see what
they say. My gut sense is that many of the proposed
examples are too complex and do not belong in element
reference topics.
Two topics need to be reworked and reviewed: <fn> and
<ph>. Ughhh ...
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
--
Alan Houser
Group Wellesley, Inc.
Consultant and Trainer, Technical Publishing
arh on Twitter
412-450-0532