Change:
- Eliot; we might want to talk more about it somewhere else, but not in the spec.
To:
- Eliot; we might want to talk more about it somewhere else, but not in the definition.
Cheers,
E.
From: <dita@lists.oasis-open.org> on behalf of Nancy Harrison <nharrison@infobridge-solutions.com>
Date: Wednesday, April 11, 2018 at 1:20 AM
To: <dita@lists.oasis-open.org>
Subject: [dita] Groups - DITA TC Meeting Minutes 10 April 2018 uploaded
Submitter's message
ActionItem:
1. Kris will post info about the precise wording for making motions, in case she's not here.
=================================================
Minutes of the OASIS DITA TC
Tuesday, 10 April 2018
Recorded by Nancy Harrison
link to agenda for this meeting:
https://wiki.OASIS-open.org/dita/PreviousAgendas
Attendance:
Robert Anderson, Deb Bissantz, Carsten Brennecke, Bill Burns, Stan Doherty, Kris Eberlein, Maria Essig, Carlos Evia, Richard Hamilton, Nancy Harrison, Alan Hauser, Scott Hudson, Eliot Kimber, Tom Magliery, Chris Nitchie, Keith Schenglie-Roberts, Eric Sirois, Dawn Stevens, Bob Thomas, Jim Tivy
Business
========
1. Roll call
Regrets: Carsten Brennecke, Dawn Stevens
2. Approve minutes from previous business meeting:
27 March 2018:
https://www.oasis-open.org/apps/org/workgroup/dita/email/archives/201804/msg00006.html (Magliery, 2 Apr 2018)
03 April 2018:
https://www.oasis-open.org/apps/org/workgroup/dita/download.php/62822/DITA%20TC%20Meeting%20Minutes%20-%20April%203%202018.txt (Schengili-Roberts, 06 April 2018)
[both] Moved by Kris, 2nded by Bill, approved by TC
3. Announcements:
New TC members: None
4. Action items
6 September 2016
Kris: Revise subject scheme example topic pulled from errata 01
19 September 2017:
Kris and Robert: Draft response to Radu's blog post and e-mail to dita-comment
13 February 2018
Kris and Bob: Fix style sheets to produce OASIS-requested formatting changes (COMPLETED)
27 March 2018
Scott and Deb: Organize event at DITA NA for TC members (COMPLETED)
Keith: Post URL to new dita.xml.org sandbox site for TC members
- Keith; not yet, will do after meeting
Kris and Tom: Check errata 02 package against OASIS previous request for changes
- Kris; will try to close that this week
03 April 2018:
Robert: Investigate whether functionality introduced in DITA 1.3 to use steps in troubleshooting topic can address Jang Graat's issue with reference topic structure
- Robert; I think it can be addressed; the precedent set by task is valid for this.
- Kris; do we need to document this?
- Robert; no, it's just good to know it before the proposal moved forward.
- Kris; I'll mark the item as completed.
5. CMS/DITA NA 2018 conference
Update on event for TC members:
- Scott; dinner will be at Marlo's near hotel, reservations at 8:30 Monday; if folks haven't indicated, pls send me mail today so I can update reservation. We have the entire mezzanine upstairs. I sent email with website.
- Kris; in previous years had a wiki page; do we need one?
- Scott; no preference.
- Kris; so, no wiki page needed.
6. "LwDITA: An Introduction" committee note
New package: https://www.oasis-open.org/apps/org/workgroup/dita/document.php?document_id=62491&referring_url=%2Fkws
Progress:
Public review requested on 14 February 2018
15-day public review announced on 23 February 2018: https://lists.oasis-open.org/archives/dita/201802/msg00069.html
Public review closed 12 March 2018
Comment resolution log from 2nd public review posted:
https://lists.oasis-open.org/archives/dita/201803/msg00074.html (Evia, Mon, 26 Mar 2018)
Package for vote:
- Kris made the motion, seconded by Tom.
Motion: "I move to approve "Lightweight DITA: An Introduction Version 1.0" and all associated artifacts packaged together at https://www.oasis-open.org/committees/document.php?document_id=62770&wg_abbrev=dita as a Committee Note and designate the XHTML version of the note as authoritative."
Results:
Yes votes: 16 (Robert Anderson, Deb Bissantz, Bill Burns, Stan Doherty, Kris Eberlein, Maria Essig, Carlos Evia, Richard Hamilton, Nancy Harrison, Alan Hauser, Scott Hudson, Eliot Kimber, Tom Magliery, Chris Nitchie, Keith Schenglie-Roberts, Bob Thomas)
No votes: 0
- Kris; since we're voting on April 10th instead of 3rd, we need to update the package with relevant date.
- Carlos; should I create a new package?
- Kris; yes, I'll put in the request using the old package, and then notify them. Congrats to all LwD folks for your work on this.
***ActionItem; Kris will post info about the precise wording for making motions, in case she's not here.
7. DITA 1.3 Errata 02
Wiki page for DITA 1.3 Errata 02
Update:
TC admin provided list of cover page corrections on 06 February 2018
Source changes implemented:
https://lists.oasis-open.org/archives/dita/201802/msg00036.html (Eberlein, 09 Feb 2018)
Style sheet changes needed:
https://lists.oasis-open.org/archives/dita/201802/msg00040.html (Eberlein, 13 Feb 2018)
Progress?
Updated package from Bob Thomas:
https://lists.oasis-open.org/archives/dita/201803/msg00059.html (Tue, 20 Mar 2018)
Volunteer to check against OASIS requirements?
Schedule
https://wiki.oasis-open.org/dita/DITA-1.3-errata-02-schedule
- Kris; Tom, lets manage our action item on this. Bob, thanks for getting it out.
8. DITA 2.0 stage three proposals
Vote
None
Initial discussion
None
9. DITA 2.0 stage two proposals
Vote
None
Continuing discussion
Redesign chunking
https://lists.oasis-open.org/archives/dita/201804/msg00039.html (Anderson, 09 April 2018)
Initial discussion
- Robert; I spent time on this last week, there are some changes, including how map hierarchies are handled when splitting into many small hierarchies. On any doc you're referencing, any child topic should appear in TOC. Also, when handling chunks to notes, splitting into a bunch of little child topics, there's no way to track to a specific instance; that's not a change from today, it's an edge case, and we're just making it explicit. Otherwise, the proposal is the same as last week.
- Tom; did you put a reminder somewhere that an example topic might need to be written?
- Robert; it's in the proposal, so it will have to be in stage 3 version. I'm not sure if it will be a complete example topic, but there's already one in the spec, so the info is in already and will be carried forward to stage 3.
- Kris; I like your file names :-) Can me move forward for vote next week?
[yes, vote next week]
10. DITA 2.0 stage one proposals
Continuing discussion
None
Initial discussion
None
11. Continuing item: What if the root element of ditabase was topic instead of dita?
https://lists.oasis-open.org/archives/dita/201804/msg00011.html (Nitchie, 02 April 2018)
https://lists.oasis-open.org/archives/dita/201804/msg00012.html (Magliery, 02 April 2018)
https://lists.oasis-open.org/archives/dita/201804/msg00019.html (Kimber, 03 April 2018)
https://lists.oasis-open.org/archives/dita/201804/msg00020.html (Nitchie, 03 April 2018)
https://lists.oasis-open.org/archives/dita/201804/msg00021.html (Kimber, 03 April 2018)
- Chris gave overview; I had some misunderstanding; Robert and Eliot pointed out my confusion and I withdraw the suggestion.
- Kris; are there changes to make in the spec that would have improved your understanding?
- Chris; the confusion was about referencing a dita file when there's no topic ID. The actual practice is to pull in all the topics in the dita element. If that's in the spec, I missed it.
- Robert; I think that's not called out right now. OT does something diff with PDF than from other outputs. It's explicitly called out that when you reference a doc containing a dita element with multiple topics, the expectation is to link to the first topic; if the link is to a ditabase doc, it's equivalent to linking to first topic. So that's the core of confusion.
- Robert; we can use the github tracker to log a need for a change in spec wording. It's not a proposal, but I can track it with that.
- Kris; that's a good thing to do with spec issues going forward, that aren't connected with a specific proposal. People have been confused before about why a link goes only to the first topic.
- Robert; I'm opening a Github issue right now.
12. New item: Definition of a root map
https://lists.oasis-open.org/archives/dita/201804/msg00025.html (Jim Tivy, 06 April 2018)
https://lists.oasis-open.org/archives/dita/201804/msg00030.html (Kimber, 06 April 2018)
https://lists.oasis-open.org/archives/dita/201804/msg00033.html (Magliery, 06 April 2018)
https://lists.oasis-open.org/archives/dita/201804/msg00034.html (Jang Graat, 06 April 2018)
https://lists.oasis-open.org/archives/dita/201804/msg00038.html (Eberlein, 07 April 2018)
Jim gave overview; I was reviewing use of the term 'root map' in spec, and the definition didn't seem to reflect the importance of the root map. So, this is just a small suggestion to add a bit to that definition.
- Kris; before 1.3, there was no definition for root map, and there was a bit of difficulty to come up with a consensus for it.
- Robert; the current definition is terse, but it's accurate and the only language that everyone could agree on.
- Bob; root map discusses the role of the map
- Robert; I think that the language that Chris suggested would be good to add; a root map is a root map whether or not it's going into a processor. I kind of like the idea of connecting root map to context.
- Jim; I agree with that, if it's generally agreed what context means; I'm not sure we need to say it's the root of the hierarchy; root probably implies that.
- Eliot; I'm uncomfortable with adding that statement; it's not quite precise. the challenge is that everything that makes a root map interesting relates to key defs and addressing. It's implicit in the way the features are defined. as soon as you say anything concrete in definition of root map...
- Kris; and this is a reprise of the controversy in our 1.3 discussion...
- Eliot; maybe we can say there are maps that are root maps and others that aren't; this is the master map you're sending to a processor.
- Eliot; we might want to talk more about it somewhere else, but not in the spec.
- Tom; is this a question we should defer to later, by setting another issue in github, to be done before spec?
- Kris; I'd be uncomfortable about redefining root map at this time. this is less targeted but on our wish list for spec is to be more precise about terminology and have a glossary. Some progress in 1.3, I'm wondering if we can discuss the idea of having glossary for 2.0. Any thoughts, Robert?
- Robert; a glossary is a good way to handle it; but would it repeat the terminology section? The current definition is accurate, it just doesn't give everything.
- Kris; I want to broaden the discussion beyond root map; how to do these kinds of explanations? with a glossary? The terminology topic lists many terms, but not all. And we have consistent disagreements about the terminology and definitions.
- Eliot; I would love a glossary, but time constraints
- Robert; I don't know how a glossary would be different from current terminology list...
- Eliot; it could have more context and guidance; the terminology list was meant to be mostly bare-bones.
- Tom; that would improve the topic in the way that Jim would like, e.g. typically a root map contains x and y, which is how you know it's a root map.
- Jim; if you have a terminology section, it needs to be self-sufficient. and it would be nice to give a hint of their importance. It doesn't get at the significance of root map. In our UI, we originally labeled it 'context map', but changed it back to be 'root map' in accord with spec when we had to deal with sharing docs with partners, who were using the original term.
- Kris; it's important for the TC to have definitions for core DITA concepts. I think many people miss the terminology topic. do we need to make it more prominent?
- Robert; or do we want to link these terms, when we use them, to the definitions? We use the term topic, but what if we added a link to the definition?
- Eliot; we could get that for free if we had glossary topics :-) To Jim's point, I wouldn't object to having a CMS use more useful terms than the ones we use, like master map, or publication map.
- Robert; I agree with that; if you're using terms from the spec, use those terms, but if they don't make sense for your audience, use terms that make more sense.
- Jim; I agree with that. that's what we did, but in a multi-vendor situation, that doesn't work, because the terms didn't match.
- Kris; our audience has to be technical implementers, so our definitions fall flat with end-users.
- Jim; if someone asked me what are the 5-6 most important things about DITA, I might include root map. So it just seemed not to carry the weight of the concept.
- Eliot; wouldn't authors coming to DITA get training that included info about the concept and use of root maps?
- Jim; yes, but how much is safe to say?
- Stan; there aren't too many parts of the spec that we can push out to companies, but this might be one of them. This may be reuse between spec and many user guides.
- Chris; I don't have a problem with using root map to identify things, but it's not appropriate for the spec to use that language, because the spec isn't managing the environment.
- Kris; I love the idea of the spec having content that could be pulled into companies' style guides, but our terminology by definition has to be terse and very techie, maybe not the best resource for end-users. I have 2 cooncrete thoughts; 1) we've talked about having a companion to the spec that would be 'DITA: the basics'; some other XML specs do that. It would be a lot of work and difficult, but maybe useful... 2) I'm wondering if there's someone who would look for instances of root map, so that we could possibly change those to be adding hyperlinks back to terminology section.
- Tom; if I were doing this, I'd wand a more complete definition, not a terse one.
Kris; linking was your idea.
Robert; I'm not sure how to improved that; with target as an implementer, that short terse definition is accurate and sufficient.
Tom; what I'd like that link to go to would be something that looks like a wikipedia page. with a short description, or that current definition, but then going on to more information that goes into more definition.
- Kris; I appreciate what you're asking for, but the spec will never have wikipedia type content; it's a legal document.
- Chris; W3C follows the convention of linking to definitions, and those definitions are terse to the point of unreadablility.
- Kris; so in order for the spec to be what it needs to be, it needs to be terse and legal.
- Robert; a glossary would be nice, but the terminology topic is useful.
- Chris; it's a question of audience and the scope of what's being described; the spec is for technical people who implement DITA. So it doesn't contain use cases around mgmt or converting to specific output formats. The spec needs definitions for processes it describes, but can't provide info about proceses outside its scope.
- Nancy; not sure a "DITA: the basics document is within our purview.
- Dick; I think it might be [within our purview], or to work on a glossary to provide context.
- Chris; but the spec is bounded, that work should be done by adoption TC.
- Kris; but the value of an intro or core concepts doc, that would come from TC, not Adoption TC and not from commercial publication.
- Chris; maybe could be a part 0 of the spec, a non-normative primer.
- Kris; this was a good discussion, though no action items coming out of it...
11:59 am ET close
-- Ms. Nancy Harrison