| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]
Subject: Groups - DITA TC Meeting Minutes 31 January 2017 uploaded
- From: Tom Magliery<firstname.lastname@example.org>
- To: email@example.com
- Date: Wed, 8 Feb 2017 16:44:25 -0800 (PST)
ACTION ITEM for EVERYONE: Please read these slides about tekom iiRDS effort:
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:
https://lists.oasis-open.org/archives/dita/201702/msg00013.html (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 further.
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 existing markup.
Tom: Why have extra domains instead of adding to the existing ones?
Bob: It's kind of a tradeoff--there's not a lot of overlap between communities who want different subsets of the domain elements.
Kris: regarding a troubleshooting diagnostic element -- is that discussion at a point where we would want a new card on the DITA 2.0 page?
Bob: Yes, consensus is solid enough
Kris: Robert please add a card to stage 1 proposals on the project page
6. New item: Conformance clause for DITA 2.0
First draft of DITA 2.0 conformance clause
https://lists.oasis-open.org/archives/dita/201701/msg00031.html (Anderson, 10 January 2017)
Text of Anderson draft:
https://lists.oasis-open.org/archives/dita/201701/msg00032.html (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 https://lists.oasis-open.org/archives/dita/201508/msg00074.html ; 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 earlier.
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 starter set.
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 normative.
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 conformance statment.
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 at all.
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 external refernece).
Eliot: I think DocBook has never stated interchange as one of the requirements.
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 this example.
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 that.
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: https://github.com/oasis-tcs/dita/projects/2
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
https://github.com/oasis-tcs/dita/projects/2#card-1429789 (Bob 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 reliant on.
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 goals.
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 considering.
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 end users.
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)
https://lists.oasis-open.org/archives/dita/201612/msg00048.html (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 sometime.
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
| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]