|
Adding attendance for the meeting:
- Zoe Lawson
- Dawn Stevens
- Kris Eberlein
- Bill Burns
- Robert Anderson
- Stan Doherty
- Nancy Harrison
- Eliot Kimber
- Keith Schengili-Roberts
- Tom Magliery
- Chris Nitchie
- Carsten Brennecke
- Scott Hudson
- Carlos Evia
- Deb Bissantz
- Joyce Lam
- Jim Tivy
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 5/31/2019 5:06 PM, Tom Magliery
wrote:
Submitter's message
New action items:
- Kris and Robert to revise this content and run it by Eliot
(Draft-comment in spec WD03, section 3.3.3, page 37)
- Robert to take an initial look at fixing this (Draft-comment in
spec WD03, section 3.4.4, page 52)
- Chris N to look at draft-comment in spec WD03, section 8.2.2.19,
page 210
=================================================
Minutes of the OASIS DITA TC
Tuesday, 28 May 2019
Recorded by Tom Magliery
link to agenda for this meeting:
https://wiki.oasis-open.org/dita/Agenda-28-May-2018
11 AM ET open
Attendance:
(TBA)
Business
========
1. Roll call
Regrets: Eric Sirois, Alan Houser
2. Approve minutes from previous business meeting:
14 May 2019
https://lists.oasis-open.org/archives/dita/201905/msg00043.html
(Harrison, 16 May 2019)
Moved by Kris, 2nd by Bill, approved by TC
3. Announcements: none
4. Action items review
13 November 2018
Eliot: Test refactoring of grammar files; due 21 May
18 December 2018
Eliot: Investigate issue re
earningAggregationsTopicrefConstraintMod.xsd; due 21 May
Pushed these two items back to end of June.
5. DITA 2.0 editorial work
Highlights?
See Editorial work completed for a full summary
Working draft 03:
https://lists.oasis-open.org/archives/dita/201905/msg00056.html
[Screen sharing of Working Draft 03]
Kris: several sections edited, some Stage 3 proposals integrated,
and markup overhauled for all RFC 2119 statements
I've been uploading a new draft every Friday, now on version 3. v1
had a reworked TOC, removed an old arch spec heading level to
reduce nesting. v2 introduced some styling for in-body normative
statements. v3 introduced a new non-normative appendix showing all
the RFC 2119 statements.
Robert: (showed TOC in screen sharing) (showed styling of
normative statements in the body of the spec) This styling may not
be what we will have in the final spec, but at least it will be
easily visible during reviews.
Kris: I think it would be nice to have some kind of styling in our
final draft, although this might look a bit like revision bars.
Scott: I can see the concern about change bars. What about a
note-like icon?
Kris: Another thing is we could add top/bottom borders.
Kris: We can do anything that we could do to style an fo-block
Eliot: I'd like to see a reference to the rule # in the appendix
Robert: I expect that to come
Eliot: That could also work as the icon
Nancy: Could we use a different character instead of a vertical
line?
Robert: We may be limited by xsl-fo on that point. We have run
into that at IBM.
Robert: I do expect to have all of these rules numbered eventually
(showed appendix of collected RFC 2119 statements)
Robert: Again this is a first, rough draft, don't expect the spec
to look exactly like this
Robert: This is an automated collection of all the normative
statements in the draft
Robert: This is already allowing me to see some things that
probably shouldn't be normative statements
Kris: It's also highlighting some things that we repeat
normatively that we probably should have only once
Tom: Are we going to have a review any time soon that will include
the normative statements?
Robert: Difficult to say. Reviewing them entails reviewing the
entire spec.
Kris: We have some challenges here. Our big issue is we
potentially make some normative statements that we shouldn't be.
There are also significant areas about DITA where we are NOT
making normative statements. Those are really hard to discern.
Tom: Should we have a review focused on normative statements?
Kris: We have an open action item for everyone to do that already,
since Chris first pulled them all together. I want to encourage
everyone to do that.
Kris: Another thing is, every week we're going to ask TC embers to
review some draft-comments. The new ones in today's draft are
almost all about normative statements. So that may be another way
we get at some of this.
Robert: It's always hard to spot absences, but if something is a
core part of DITA that doesn't mean we need a normative statement.
If something simply "is", that doesn't mean we need a "must" sort
of statement, it's simply a fact. E.g. there's no need to have a
normative statement that says a topic must have a title; the DTDs
already enforce that.
Kris: Let's move on to a review of draft comments
Robert (scrolls to first draft-comment in spec draft, page 37,
section 3.3.3)
Kris: Should this be normative?
Eliot: Either it should be stated in a direct way, in terms of the
precedence of the source of the value rather than how a processor
might work, that is the processing should be implicit in the
rules. But if this behaviour is already implicit in the rules than
there should be a non-normative note (if it's here at all).
Kris: I don't know whether what we're stating here is already
normatively stated in how our processes handle values for DITA
attributes.
Robert: I don't think this is stated elsewhere.
Robert: So Eliot what you're saying is this intro clause should be
something like "The effective value for a DITA attribute IS..."
Eliot: Yes, it should be declarative not procedural
Kris: So we need to change the introductory sentence
Eliot: I have a concern, which is that this also affects cascading
values of attributes in maps. We need to be careful we're not
restating this rule.
Eliot: Also in this list, items 1&2 come from XML behavior,
it's not until #3 that we get to things that are needed for DITA
Robert: The editors need to make sure this content is not
duplicated. We can't just delete it because we lose the part about
defaultSubject
Eliot: The list altogether is good, but perhaps there needs to be
another statement that says that these rules apply when cascading
is needed.
Kris: This was something we introduced in DITA 1.3.
Eliot: I think the previous paragraph "The default attribute
values ..." could maybe be the normative statement
Robert: That's probably correct
Eliot: Then what follows is a nice explantory note
ACTION: Kris and Robert to revise this content and run it by Eliot
Next draft comment: (page 52 in section 3.4.4)
Kris: This one is self-evident
ACTION: Robert to take an initial look at fixing this
Robert: This probably needs the same reworking that Eliot
mentioned earlier
Robert: Maybe defaultSubject should be added here, maybe between
steps 9 and 10
Next (Section 6.4.4, page 150)
Kris: A five-year-old comment! We can finally address this,
because it will no longer potentially create backwards
incompatibility
Kris: any objections to the change?
(no objections raised)
Next (Section 8.2.2.19, page 210)
Kris: This may not be a matter for whole-TC discussion. We'll pass
on this for now
ACTION: Chris N to look at it
Next (Section 8.2.2.22, page 213)
Kris: We put all statements about formatting into an appendix. We
do make some normative statements about rendering, although we
don't use "must" statements, but we decided there are some places
for "should" statements
Eliot: I forget our distinction between "formatting" and
"rendering"
Kris: Formatting being strictly styling per se, rendering falling
more in the example of is particular content exposed or not
exposed. Are there fallback mechanisms. It's a hazy grey area.
Eliot: I think the word "preserved" is problematic. It would be
better to just mention that they are rendered in some way. E.g.
poetry can use slashes.
Robert: agree
Kris: This is exactly the kind of discussion we should have about
many of these topics, some of which have been around since DITA
1.0
Kris: Suggested wording: Line breaks are preserved or otherwise
represented.
We can massage the wording
Eliot: I would be more direct, not have a list, but just a
statement, "Processors should do this and that"
Robert: the critical part to call out here is the line breaks, not
the white space.
Robert: I'm picturing this now as a paragraph that SHOULDs the
line breaks, and another note about the white space is just
informative
6. Stylesheets
Update
Work merged in GitHub
Open items that need fixes
Work in development
See https://wiki.oasis-open.org/dita/stylesheetBacklog
(screen-sharing of backlog)
Kris: We have two things currently broken in the style sheets -
cross refs (broken in DITA OT) and indentation for shortdesc and
related links is not being rendered correctly. But you've seen
results of the biggest recent changes to style sheets. We'll
continue to work forward. Currently the numbering in the PDF comes
directly out of templates in that plugin. But we want the
numbering for all of our spec outputs to come from a single
ordering plugin to ensure consistency across output formats.
Robert: That actually is what blocked me from getting numbers in
the appendix of normative statements. I don't want to implment
that twice for HTML and PDF.
7. Show-and-tell of how normative statements in spec are now
rendered
Working draft 03:
https://lists.oasis-open.org/archives/dita/201905/msg00056.html
Normative instances in body text
(Non-normative) Aggregated in an appendix
Discussion
[We covered this under another item above]
8. Draft comments in latest working draft from TC attention
We will review and discuss them
Working draft 03:
https://lists.oasis-open.org/archives/dita/201905/msg00056.html
[We covered this item out-of-order earlier in the meeting]
9. Name of spec that contains CTR etc
Technical Content versus Technical Communication? Something else?
https://lists.oasis-open.org/archives/dita/201905/msg00048.html
(Eberlein, 19 May 2019)
Lots of responses ...
https://lists.oasis-open.org/archives/dita/201905/msg00052.html
(Evia, 21 May 2019)
Kris: What shall we call our release that contains CTR, bookmap,
glossary, all of the related domains? Do we call it Technical
Content, Technical Communication? After the polling in the group,
is there anything better than Technical Content? Glossary is a
feature that is more generic than technical content.
Kris: Carlos what were your reasons for not using Technical
Communication?
Carlos: It goes against the efforts I make to tell people what
this spec is broadly useful for.
Kris: We don't have to decide this today but we do need to decide
this in fairly short order for OASIS process purposes
Robert: Carlos's comment makes sense to me from what I've heard in
industry. "Tech Comm" is so broad that trying to use that here
seems wrong. "Technical Content" seems off a little, too.
Carlos: If this were 1995 we could say "documentation" but it
isn't
Eliot: Aren't we really talking about hardware/software
documentation when we talk about CTR? The two domains +
troubleshooting stuff? But I guess that leaves out
machineindustry?
Robert: that's kind of hardware
Kris: How about DITA for Technical Documentation?
Scott: Even doc has kind of a print sound as opposed to "content"
Carlos: The thing is "content" is now a more granular kind of
thing.
Tom: Maybe we need a term that gets away from the word "Technical"
Eliot: Maybe "task-oriented content"? Really much of this kind of
content is driven by tasks
Deb: Medical content is often very conceptual
Bill: Ours, too
Zoe: What's difficult is in my brain DITA is CTR so calling out
that part as something different from DITA hurts my brain
Kris: This is something we all need to mull over. In 1.3 we really
began to emphasize that the real building blocks of DITA are topic
and map and that the others such as CTR are about more specific
use cases
Chris: What we traditionally called technical conteng is a
conflation of CTR that are not technical in a series of domains
that are profoundly technical. Finding an umbrella is challenging.
Long thought it would be valuable to split them up, but there are
logistical barriers.
Kris: people please take a look at the PDFs (DITA 2 working draft
03 and also the "to be named 2.0" under item 10 below)
10. DITA for 'To be named' version 2.0
Update on editorial work completed
Working draft 01:
https://lists.oasis-open.org/archives/dita/201905/msg00047.html
(Eberlein, 19 May 2019)
Work to be done:
https://wiki.oasis-open.org/dita/ditaTechnicalContent2.0backLog
12 noon ET close
-- Mr. Tom Magliery
|