Note that these originally went to the list with the subject line
"Minutes 31 January 2017"
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 682-2290; kriseberlein (skype)
On 2/8/2017 7:44 PM, Tom Magliery
ACTION ITEM for EVERYONE: Please read these slides about tekom
Minutes of the OASIS DITA TC
Tuesday, 7 February 2017
Recorded by Tom Magliery
link to agenda for this meeting:
Meeting opened: 8am Pacific time
1. Roll call
Regrets: Nancy Harrison, Keith Schengili-Roberts
2. Approve minutes from previous business meeting:
(Tom Magliery, 31 January 2017)
Motion to approve: Kris
3. Announcements: [NONE]
4. Action items: [NO PROGRESS TO REPORT]
5. Report from Tech Comm SC (Bob Thomas)
Subcommittee met on Friday January 27, discussed 3 things
1. We received feedback that we were missing markup for a
diagnostic phase in troubleshooting. If a condition has multiple
possible causes there may be need for diagnostic steps to steer
the reader to the correct trouble solution. Right now it looks
like we may want to add a specialization of
called something like "diagnostic". We will be
discussing this more. Robert mentioned that sometimes things
with troubleshooting are complex and may have need for something
more elaborate than the current model. It needs to be discussed
2. Optimizing content models for authoring. We did not decide
anything -- just discussion. There is a general desire to come
up with easier starting points for authoring groups, with not so
much mixed content available. Also an easier way to
configure/constrain things. Also have an interest in simplifying
the domains attribute.
3. One thing that has come out of recent DITA listening sessions
is that the programming and software domains DITA are missing
markup for things like object-oriented programming, web
services, etc. Not sure where we're going to go with that.
Inlines in DITA generally are not as robust as the ones
available in DocBook. My guess is that markup for these will be
in new domains rather than enhancing existing one. Probably need
a mechanism for providing markup for uncovered programming cases
so user communities would not feel they need to overload
Tom: Why have extra domains instead of adding to the existing
Bob: It's kind of a tradeoff--there's not a lot of overlap
between communities who want different subsets of the domain
Kris: regarding a troubleshooting diagnostic element -- is that
discussion at a point where we would want a new card on the DITA
Bob: Yes, consensus is solid enough
Kris: Robert please add a card to stage 1 proposals on the
6. New item: Conformance clause for DITA 2.0
First draft of DITA 2.0 conformance clause
(Anderson, 10 January 2017)
Text of Anderson draft:
(Eberlein, 11 January 2017)
[OASIS] Guidelines to Writing Conformance Clauses:
Technical Advisory Board (TAB) comments from their review of
DITA 1.3 in 2015:
See summary in
; search for Conformance
Robert: Brief summary is that this is what got the most negative
attention from the OASIS TAB (Technical Advisory Board). TAB is
a small group of OASIS admins/volunteers who review standards. A
conformance clause is important because that's how an
implementation knows it's following the standard. Our
conformance clause in DITA 1.3 was not really acceptable but we
were limted by what we've done beore. We really need to do
something better for 2.0.
Kris: DITA 1.0 and 1.1 went out without conformance clauses
although OASIS rules from 2007 would have called for DITA 1.1 to
contain one. We added one for 1.2 and that's essentially what we
used for 1.3 but we took a lot of heavy commentary from the TAB.
Kris: any questions/clarification needed?
Eliot: The draft looks good as a starting point. We'll have to
think carefully about the list of features. There's also a
challenge in terms of how the writing is strucurerd to make it
clear that there are no mandatory features, only that the
requirement is "if you implement a feature, this is how you must
do it." We have this further down but it needs to be said
Robert: Yeah. The only thing I'll say is it makes me sad that we
can only have a short and explicit one and we have to write it
in a way that if someone only reads the middle paragraph they
would not get it. Also, the list of features here is meant as a
Eliot: I like the approach. I feel strongly that we should not
have any rendering requirements in the spec.
Robert: Yeah, we've had that discussion in the past.
Kris: The current spec has normative statements about rendering.
Robert: We're going to have to consider them one by one.
Eliot: Don't worry, none of them are appropriate.
Eliot: We've talked about performance of grammars. Robert and I
agree that coding details of grammars don't need to be
Kris: That may well drive changes in what we have for content in
the spec as well. Maybe we move some coding requirements into an
auxiliary non-normative doc or appendix. Both Robert and I came
to this agreement as well during work on 1.3.
Kris: Back to specifics about what we do in 2.0, there's a link
on the front page to OASIS guidelines for conformance clauses.
Please everyone take time to look at this. Basically they call
for us to be very explicit in our conformance clause. That our
conformance clause should have very clear targets. E.g. a target
might be a DITA processor or a DITA document. Then we should
have every conformance clause tied back to normative statments
in the body of the spec. By saying "normative" I'm talking about
those upper case MUSTs or SHOULDs. This will involve some
rewriting of the spec so that we can easily reference, possibly
even by numbering things, to be tied back to statements in the
Eliot: It occurred to me that DocBook 5.1 just got published, I
was curious what their conformance statement says. They only
discuss conformance of instances -- no processing reuqirements
Robert: I noticed the same a month ago. It said something like
"you have to follow all the rules in Norm's book" (i.e. an
Eliot: I think DocBook has never stated interchange as one of
Robert: Ours is a little quirky in that it has all these
features that interact. There has to be an implementation to go
along with that.
Carlos: I assume we will need one of these for LwDITA, too.
Kris, Robert: absolutely.
Robert: The OASIS TAB wanted us to go through the entire spec
and find every instance of MUST, MAY, etc. and explicitly list
all of them in the conformance clause.
Eliot: I'm looking at the guide to writing conformance clauses
and their example does not provide much detail. It just
references general things. Robert's draft is more detailed than
Robert: The TAB's comments were more specific and detailed than
their own guidelines. This is an attempt to find middle ground.
Eliot: "to conform you must be conforming"
Robert: Yes, some specs have actually gone out with that.
Technically it's ok, but not helpful.
Kris: I like what you've done with isolating these 9 features
and giving potential implementations these 9 things they can
make claims of conformanace against.
Scott: Just to clarify about DocBook, the main difference with
DITA is that we do have that interopability constraint.
Kris: Yes, interoperability and specialization
Scott: I'm wondering if we can add a generic statement that
documents have to be valid according to the grammar so we don't
have to be too specific about some of those details.
Kris: Robert's X.2 section in the draft is supposed to cover
Scott: Ah, yep, it does.
Kris: any more questions, concerns, feedback about direction?
Kris: LwDITA folks be sure to also take all of this into
consideration as well.
7. Continuing item: Formal work on DITA 2.0
Project page at the GitHub repo:
Kris: We put quite a lot of time into our process for DITA 1.3,
which by and large was successful. Looking through voting
members we have about 1/3 who were not actively involved in 1.3.
E.g. Dawn, Maria, Mark, Keith, Eric, Carsten, Carlos.
Accordingly we want to make sure we go over the process. Not now
but I have asked for volunteers to work with Robert and me in
putting together a presentation to the TC. Tom and Maria
volunteered. We will have that on an upcoming agenda ASAP to
give people a firmer grounding - what are the stages of
proposals, our expectations, etc.
Items for discussion:
Separating base and technical content
Thomas for Tech Comm SC)
Bob: We want to extract content out of its overview and put it
on its own. Section 2.7 deals with tech content, that would be
moved out of the current standard and into this new one.
Kris: Let's back up and give a little context: For DITA 1.0 and
1.1 there was no "base". For 1.2 we introduced the idea that
there was a core architectural base for DITA consisting of
topic, map and subect schemes; on top of that we layered
concept, task and reference. What's up for discussion now is the
idea that we might further separate that for 2.0 to enable base
vs. tech content specializations to be distributed on different
timelines. Bob, what would be the advantages.
Bob: One advantage is to consider that for 2 of the 3 items from
the tech comm SC (troubleshooting diagnostic element, and the
enhancing of programming markup)-- neither of those should have
any dependency at all on the base. That effort is pretty much
orthogonal to work on the base standard. But as it is now we
don't have any way to release these changes without the 4-5 year
iteration of the base standard. That's the chief rationale.
Another rationale is to establish caretaking and ownership of
portions of the standard. E.g. with Learning and Training there
was a desire to do the same thing with that.
Eliot: I definitely support this direction. I would like to see
DITA consisting of a base spec and that all specializations are
separate specs built on top of that.
Don: Would this indicate that most of the conformance discussion
could be limited to this new base document?
Bob, Kris, Robert: I would think so.
Robert: Realistically I think we sort of meant that with DITA
1.3 as well.
Kris: I support this idea but we need to be careful with
implementation details of it. E.g. if we separate tech content
from base, then the grammar files need to be separate. So what
is distributed with the tech content release?
Robert: I have thought about some of these difficulties and am
not sure of the answers.
Bob: Yeah, it's straightforward on the surface but once you
start digging it's kind of dicey because of all the things
you're relying on in the spec. It may turn out that in
conformance you have to say what portion of the base it's
Kris: From a usability perspective (we have a lot of folks who
represent tech comm users) we will have to look at the usability
of downloading grammar files and/or the specification, what will
they get? How do we handle this in a way that lets us meet our
Robert: There are going to be probems with version numbers too.
Chris: These usability costs will hit tools vendors and
consultants more than end users.
Kris: That's a big one. With a history of speaking out against
complexity, usability is something I want to cotinue
Stan: In 2.0 we're going to bump into more disruptive things. We
might want to build in some kind of alpha testing with users. It
might be good to cook that in ahead of time if possible.
Kris: What are you proposing we do?
Stan: Maybe when we have some components available, carve out
some volunteers to play with it for a month, get feedback.
Especially if we run into feedback from OASIS.
Kris: I like the idea, but realistically it's pretty late in the
game before we have strong enough working prototypes.
Robert: Keep in mind it's virtually impossible to say now what
that might look like.
Dawn: I agree this is a good idea; I was just going to volunteer
to help figure out what it might look like.
Kris: Will you be active in the tech comm subcommittee?
Dawn: I haven't been yet because JoAnn was, but I will be.
Kris: Packaging will be a big thing that we are going to be
considering. It was a big thing we did for 1.3 with the three
editions. What we're looking at for 2.0 is how we can have these
as separate deliverables, either stand-alone or so simple to
integrate or compile that we don't have a usability hit for our
Kris: Back to item 7, how do we want to move on this? Is it
ready for more discussion?
Eliot: I move we put this forward to stage 2
Kris: Any concerns?
Robert: Yes: It's going to be hard!
Kris: OK, we're moving this forward to stage 2
8. New item: tcworld iiRDS slides (English translation)
(Eberlein, 07 December 2016)
Kris: This is a new standard Tekom was working on. I translated
the German slides, link above. Everyone please look at these
this week, we will discuss next week. I may ask whether we want
someone from the Tekom working group to present this to us.
ACTION ITEM FOR EVERYONE: Please look at this.
9. Continuing item: Listening sessions
Portland, OR -- Rescheduled for January 2017
Research Triangle Park, NC
Seattle, WA -- Scheduled for 24 January 2017
Kirkland, WA -- Scheduled for 25 January 2017
Kris: Any updates on the sessions planned for Portland and
Austin? [no response]
Kris: How did the ones in Washington go?
Scott: We had two sessions, Seattle and Kirkland, turnout was a
little disappointing. We went through various avenues to get the
word out so it's unclear why. That said, we had great
discussions with the companies that were there. Four different
companies at Seattle and essentially just our host for Kirkland.
Comments overall were good, no major complaints but a few
suggestions regarding some of the troubleshooting side of
things. We have already brought that to the tech comm SC.
Essentially it was about trying to create more faq-like content.
Another interesting one was regarding abstracting out metadata,
relating it to one or more topics in an RDF-like scenario. Any
other comments from Keith or others?
Kris: Keith's not here today. Others with comments/questions?
Dawn: We have another listening session in San Jose on Feb 21st.
Scott: Lesson learned from Seattle: The earlier we get word out
the better. We did dita-users, twitter, linkedin, and had
comtech and IXIASOFT pinging their user base.
Scott: Also we may want to try doing a virtual-only session
Kris: That might be a good item for next week's TC meeting.
Perhaps we should have one through OASIS.
Stan: Some of these action items are living in the Adoption TC
as well. We may have some overlap.
Kris: Thanks for bringing that up, yes, we will.
Meeting closed 9am Pacific time.
-- Mr. Tom Magliery