[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Eberlein feedback about troubleshooting proposals
|
I wanted to do my review as quickly as possible, so please excuse me
if my comments seem terse. Thanks for all the hard work in bring
these proposals together! Proposal #13086
Proposal #13096
Proposal #13098
Architectural spec topics
--
Best, Kris Kristen James Eberlein Principal consultant, Eberlein Consulting Co-chair, OASIS DITA Technical Committee Charter member, OASIS DITA Adoption Committee www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype |
Minutes of the OASIS DITA TC
Tuesday, 26 June 2012
Recorded by N. Harrison
regrets: Michael Priestley, Scott Hudson
Standing Business
=================
last week's minutes:
https://www.oasis-open.org/apps/org/workgroup/dita/download.php/46335/minutes20120619.txt (Harrison for June 2012)
Don moved to approve, seconded by Joann, approved by TC
Subcommittee reports:
- No reports this week
- July report by Tech Comm SC moved to second week (July 10)
Announcements:
none
Business
========
1. DITA 1.3 proposals, stage 1: http://wiki.oasis-open.org/dita/DITA_1.3_Proposals-triage
Ready for discussion: None
Ready for votes (simple majority): None
2. DITA 1.3 proposals, stage 2: http://wiki.oasis-open.org/dita/DITA_1.3_Proposals-stage2
Ready for continued discussion:
13096 Add a troubleshooting section with <task>
https://www.oasis-open.org/apps/org/workgroup/dita/download.php/46314/StepTroubleshootingProposal13086.html (updated 21 June 2012)
Discussion centered on 1) what changes needed to be made to the proposal before it can be voted on, in particular the need to completely specify the details of where, within <taskbody> the section would occur, and 2) whether the vote could be taken today. The consensus was that the new section should go after <results> and before <example> The group agreed that in light of the fact that the discussion on this item had bbeen continued from last week, the vote on it has to be taken next week, July 3rd.
Seth agreed to update the proposal with the required information
- declaring the section a specialization of topic/section
- ordering, after <results> and before <example>
- having a guideline for automatic text but not making it mandatory (i.e. 'processors may have to' rather than 'processors will have to')
- proposal will apply to both general and strict task
- <title> will be disallowed, so authors can't name it arbitrarily; this is different from <example> but consistent with the other specialized sections in task
Resolution; seth will update proposal for TC review; TC will vote on proposal next week
Stage 2 items ready for vote:
13098 Add an attribute to note for troubleshooting
Proposal was voted on; results were 14-0 for approval.
Voting 'Yes' were:
Robert Anderson, Deb Bissantz, Michael Boses, Thilo Buchholz, Don Day, Kris Eberlein, Stan Doherty, Joann Hackos, Nancy Harrison, David Helfinstine, Eliot Kimber. Tom Magliery, Chris Nitchie, Seth Park
13086 Add a troubleshooting element within <step>
Proposal was voted on; results were 14-0 for approval.
Voting 'Yes' were:
Robert Anderson, Deb Bissantz, Michael Boses, Thilo Buchholz, Don Day, Kris Eberlein, Stan Doherty, Joann Hackos, Nancy Harrison, David Helfinstine, Eliot Kimber. Tom Magliery, Chris Nitchie, Seth Park
On hold; dependency on "Simple DITA" proposal
Proposal #13004: Scoped keys (Champion, Chris Nitchie) http://www.oasis-open.org/committees/download.php/44886/1-3proposal-13004.htm
3. DITA 1.3 proposals, stage 3:
Several proposals are now in this phase; this item is a reminder that 2 or more reviewers are needed on material prior to bringing it to this stage for approval.
Kris brought up this topic just to remind champions of proposals that have been accepted for Stage to enroll 2 reviewers for Stage 3 work. The only proposal with reviewer is Robert's (13) for which Kris, Stan, and Don have volunteered to be reviewers. TC members are asked to consider which proposals they would be willing to review.
4. Question about navtitle in topicgroup
https://www.oasis-open.org/apps/org/workgroup/dita/email/archives/201206/msg00045.html (Radu Coravu, forwarded by Eberlein)
https://www.oasis-open.org/apps/org/workgroup/dita/email/archives/201206/msg00046.html (Kimber)
https://www.oasis-open.org/apps/org/workgroup/dita/email/archives/201206/msg00048.html (Anderson)
This item is in response to a question by Radu of OxygenXML; given that you can put a <navtitle> in an <itemgroup>, should an editor display that navtitle?
The dsicussion noted that the spec, in discussing processing details, doesn't distinguish between processing for publishing and for authoring; this particular question is about editor, not publishing, behavior, and they often need to be quite different.
The TC acknowledged that we need to supplement the spec with some information about general differences between processing implementation for editing and publishing, especially in relation to the navigation hierarchy, which turns out to need clearer definition (TOC-only? TOC + links?).
Also, there is some confusion among users, since DITA 1.2 introduced metadata elements, over how/when to use metadata elements vs. metadata attributes.
Resolution: In this case, the answer for Radu is that 'yes, the <navtitle> should be displayed in that context'.
ACTION ITEM; TC needs to discuss what we mean by 'navigation hierarchy', and to look at the metadata element/attribute confusion issue
5 Processing reltables
https://www.oasis-open.org/apps/org/workgroup/dita/email/archives/201206/msg00050.html (Casey Jordan, forwarded by Eberlein)
The issue is on reltable processing; should a processor form a union and remove duplicates?
After some discussion, the consensus was that Casey's approach was generally correct. There are 3 aspects to casey's question;
1. forming unions of all relationship 'links within maps'
2. eliiminating duplicate relatinships; this involves implementation detailm, but we all agree with him in principle
3. the more general issue of how links relate to display,; this is too general to really consider, and definitely an implementation detail. The TC would need a more specific question in order to give him a better answer.
6. Is a <tasksection> Element Appropriate?
http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/201205/msg00040.html (Kimber, 24 May 2012)
http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/201205/msg00041.html (Hackos, 24 May 2012)
http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/201205/msg00043.html (Eberlein, 25 May 2012)
[This discussion had been postponed until all interested parties were present.]
Kris: This proposal was brought up in response to a request to have multiple sets of steps within task (which was originally going to be possible within a 'general' task, but turned out not to be)
Eliot: the strawman proposal isn't legal,it requires steps within section, but steps are only allowed in taskbody,
Robert: The real question is wheether this request has been addressed by the proposal for a troubleshooting topic model, but we still haven't seen the details for that model.
Seth; i think Bob Thomas took this back and whipped up a new recipe for a troubleshooting topic; we're waiting on the new topic proposal from Bob.
Resolution: Seth will bring this back to the TechComm SC to find out if this item is still required/desired, or if it's subsumed by troubleshooting topic.
closed at noon
Minutes of the OASIS DITA TC
Tuesday, 19 June 2012
Recorded by N. Harrison
regrets: none
Standing Business
=================
Last week's minutes:
https://www.oasis-open.org/apps/org/workgroup/dita/download.php/46241/minutes20120612.txt(R. Hamilton)
Don moved to approve, seconded by Deb Bissantz, approved by TC
Subcommittee reports:
- No reports this week
- July report by Tech Comm SC moved to second week (July 10)
Announcements:
none
Business
========
1. DITA 1.3 proposals, stage 1:
Ready for discussion: None
Ready for votes (simple majority): None
2. DITA 1.3 proposals, stage 2: http://wiki.oasis-open.org/dita/DITA_1.3_Proposals-stage2
Ready for discussion:
13098 (Blaisdell)
Add an attribute to note for troubleshooting
13086 (Blaisdell)
Add a troubleshooting element within <step>
13096 (Blaisdell)
Add a troubleshooting section with <task>
The TC decided to discuss all the troubleshooting items before voting on any of them; in the end, we decided that we'd completed discussion of the first 2 (13098, 13086) and would vote on these next week, while continuing the discussion of the last one (13096).
Discussion of 13098:
Reference: https://www.oasis-open.org/apps/org/workgroup/dita/download.php/46235/NoteAttributeTroubleValue.html
Susan Blaisdell went over the Stage 2 proposal for this. There was general consensus that 13098 was straightforward and there was no reason to oppose it.
Resolution: Susan will submit updated proposal, which will be voted on next week.
Discussion of 13086:
Reference: https://www.oasis-open.org/apps/org/workgroup/dita/download.php/46251/StepTroubleshootingProposal.html
Susan went over the Stage 2 proposal for this as well. The initial consideration was whether the added element would be optional; the TC generally agreed that it should be.
There was also concern about whether authors might not understand where to use <note type="troubleshooting"> vs. where to use <steptroubleshooting>; there is, in fact, no syntactical way to keep an author from putting a troubleshooting note within a <steptroubleshooting>. It was agreed that these troubleshooting proposals would require significant documentation in the spec. (and perhaps in a white paper?) in order to give guidance to authors. To reduce the complexity, it was suggested, and agreed, that the best way to do this was to have <steptroubleshooting> be specialized from <topic/note>, with a FIXED type of "trouble" - the new proposed <toe> type, rather than the original specialization of topic/itemgroup. Susan agreed to update the proposal to reflect this change.
The next discussion was on where, within the children of <step>, it should appear. Most of the TC wanted to have it following <stepresult> as an optional sibling of that element. However Eliot and Seth Park wanted a more flexible structure, where the group of elements that come after <info> would be a repeatable group; this would allow the <steptroubleshooting>, as well as all the other elements in that group, to be in any order. It was poionted out that this would require major changes to both the general and the strict task model. Eliot may want to make a proposal to loosen the general task model, while leaving the strict task model as it is. At the end, the TC decided to leave the new element after <stepresult>.
Resolution: Susan will submit updated proposal, which will be voted on next week.
Discussion of 13096:
Reference: https://www.oasis-open.org/apps/org/workgroup/dita/download.php/46253/TaskTroubleshootingSectionProposal.html
Susan reviewed the proposal for adding a <resulttroubleshooting> section to <task>; Joann noted that it has the same rationale as other proposals - the goal is to cue authors and information architects that they need to provide troubleshooting info as part of a task.
Eliot noted that while the proposal indicated that the new section would go after <result> and before <postreq>, it didn't specify whether it would go before or after <example>, which is also between <result> and <postreq>. Consensus was that it should go before <example>, immediately after <result>
There was discussion of whether a title whould be autogenerated; none of the other parallel sections in <task> have a default title, so that would be inconsistent.
Robert also suggested that the element should be <tasktroubleshooting> rather than <resulttroubleshooting>; TC agreed; Susan will update the proposal.
It was generally agreed that the Stage 2 proposals for these items need to include a description of the interaction between the 3 items. There also needs to be a description of the doc changes required.
Resolution: discussion to be continued next week.
meeting closed at noon
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]