Groups - DITA TC Meeting Minutes 2 April 2019 uploaded

[Nancy Harrison<nharrison@infobridge-solutions.com>]

        Submitter's message
        ActionItems:
1. Nancy will create mockup of 2.0 techcomm package, especially grammar files.
2. Kris will send out announceent to other TC members to see if they want to join TC dinner at DiTA/NA
3. Kris will provide more info about Weds. panel for online agenda;  will ping dawn about it; Kris and Robert have 2.0 slides to provide, but would like to see slides from any TC members doinga 2.0 presentation
4. Tom will create a summary of examples in arch spec.
5. All TC members: look thru Chris's conformance email and 1.3 normative statements; what's missing? what's duplicative? what's nonsensical? How should we mark them up so we can get a clean extraction to build an appendix?



=================================================
Minutes of the OASIS DITA TC
Tuesday, 2 April 2019
Recorded by Hancy Harrison
link to agenda for this meeting:	
https://wiki.OASIS-open.org/dita/PreviousAgendas


Attendance:
Robert Anderson, Carsten Brennecke, Bill Burns, Stan Doherty, Kris Eberlein, Carlos Evia, Hancy Harrison, Alan Houser, Scott Hudson, Eliot Kimber, Tom Magliery, Chris Nitchie, Jim Tivy, Zoe Lawson 		  


Business
========
1. Roll call
        Regrets: Deb Bissantz 


2. Approve minutes from previous business meeting:
    26 March 2019
       https://lists.oasis-open.org/archives/dita/201903/msg00043.html (Harrison, 27 March 2019) 
Moved by Kris, 2nd by Bill, approved by TC


3. Announcements:
    New TC members: Zoe Lawson, Casenet LLC (previously at IBM)  


4. Action items
    21 August 2018
        Kris & Robert: Perform the best edit of multimedia topics that they can do in time available; due 23 April 
    11 September 2018
        Kris: Review conversation with Joe Pairman, e-mails about metadata, and TC discussion in late 2017/early 2018; summarize to TC: due 02 April 
    13 November 2018
        Eliot: Test refactoring of grammar files; due 07 Mary
        Spec editors: Finish incorporating changes from DITAweb review; due 09 April 
    18 December 2018
        Eliot: Investigate issue re earningAggregationsTopicrefConstraintMod.xsd; due 07 May 
    22 January 2019
        Kris and Robert: Schedule meeting to plan moving forward on implementing complete DITA 2.0 proposals (COMPLETED) 
    29 January 2019:
        Carlos: Set up regularly scheduled calls between DITA 2.0 and LwDITA spec editors; due 26 April 
    05 February 2019:
        Kris: Add fix to 'xmlnamespace' topic to list of things to fix in 2.0 (COMPLETED) 
    12 February 2019
        Tom: Summarize meeting with Robert and Scott to go over the additional examples Stan proposed for DITA 2.0 (COMPLETED) 
    19 February 2019
        Alan and Tom: Have functional stylesheets for DITA spec (PDF and XHTML) by DITA NA conference
- Alan; I think this might be considered done; we're able to generate the docs.
- Kris; issues are that title and footers are being produced as though it's an errata doc, even though it's supposed to be a spec, so it's not really functional.
- Alan; ok, now I understand.
- Kris; just fyi, we got folks to commit to deadlines for AIs last week; can you ommmit to a deadline for this? 
- Alan; by 4/22
    05 March 2019:
        Alan: Update DITA 2.0 files for appropriate elements with LwD hint values for @format and create a pull request 
        Michael Priestley: Propose methodology/syntax for mapping DITA class and outputclass attributes to HTML class attribute -- Need deadline 
- Alan; I'll need to get help from Michael for my part of this 
- Kris  can you contact him about that, and a deadline for his piece?
- Alan; will do



5. Review of DITA 2.0 proposal deadlines
    https://wiki.oasis-open.org/dita/DeadlinesDITA2.0 
- Eliot; waiting for review from Robert


6. Stylesheets
    OASIS has agreed to build actual style specifications, with our help
        https://lists.oasis-open.org/archives/dita/201903/msg00012.html (Eberlein, 04 March 2019) 
    Updates on committee note:
        Now runs on DITA-OT 3.3 (both PDF and HTML5 
    Update on spec:
        Now runs on DITA-OT 3.3 
    Latest news: OASIS is willing to minimize differences between specifications and committee notes 
- Kris; waiting for word from OASIS on these.


7. Content of the Technical Content package for DITA 2.0
    https://lists.oasis-open.org/archives/dita/201904/msg00000.html (Harrison, 02 April 2019)
    More info from Harrison
        https://lists.oasis-open.org/archives/dita/201904/msg00002.html (Harrison on 28 March, forwarded by Eberlein on 02 April 2019)
        https://lists.oasis-open.org/archives/dita/201904/msg00003.html (Harrison on 28 March, or spec, but no grammar files, and we have 
- Nancy; We know we're splitting out the techcomm package - and the L&T package - into separate profiles for 2.0, and given how many DITA users use the techcomm package, I want to give them a head up on what's coming in 2.0 at DITA/NA.  But because we don't have an iteration of techcomm 2.0, I can't give them as much info as I'd like. So I'd like us to discuss and come to some agreements about techcomm 2.0.  E.g., what will the folder structure look like?  Will we have separate bookmap folder parallel to techcomm, as we do now?  Will we replicate a topic.mod in the techcomm/[rng|dtd] folders?  What about xnal?
- Robert; good questions, but I don't have time to work on this right now.
- Kris; the rationale for this work was reducing dependency between base, techcomm, L&T (as well as LwD). 
- Kris; we do have a separate github repo for techcomm, that needs to be fully populated.  And we need to have a standing item on 2.0 packaging; with the state of spec, state of repo, etc., starting with a disussion of how to package techcomm.  One goal of repackaging 2.0 is to get rid of weird names and folder structures, we need to look at how to rationalize them.
- Nancy;  I can try to work up a proposal for new techcomm profile, including grammar files, though I don't know much about rng, and would be better able to do the dtd grammar files
- Robert; but rng is normative, not dtd...
- Scott; if you want help  with rng, i can help
- Nancy; thx, scott.
***ActionItem: Nancy will create mockup of 2.0 techcomm package, especially grammar files.


8. Continuing item: CMS/DITA NA 2019
    Dinner Sunday after reception in an informal settin
***ActionItem:  Kris will send out announceent to other TC members to see if they want to join
    Brainstorm about how we could use a table in the vendor area most effectively 
    Lunch before Wednesday DITA 2.0 panel
Kris; we'll need to send out for this - CIDM doesn't provide one.
***ActionItem: Kris will provide more info about Weds. panel for online agenda;  will ping dawn about it; Kris and Robert have 2.0 slides to provide, but would like to see slides from any TC members doing 2.0 presentations (Eric, Nancy, ??)
    Wiki page; has signup for DITA table

     
9. Notes from the meeting to review examples Stan proposed during the DITAweb review"
    https://lists.oasis-open.org/archives/dita/201903/msg00040.html (Magliery, 26 March 2019)
    Points for TC consideration:
       o Guidelines for examples in element-reference topics
       o Guidelines for examples in (currently) archSpec topic
       o Action item: Harvest recommendations for specific DITA 2.0 topics and add them to list 
- Tom; we need to look at these notes when examples come up for consideration. 
- Kris; your item was about getting a consensus from looking at Stan's examples; what did you find? 
- Tom; one guideline was that examples shouldn't illustrate complexity, but rather illustrate elements' basic function; samples should illustrate common cases or best practices.  Best practices came up when we saw that some of stan's went against best practices; e.g. 'note' example essentially contained a proedure inside a note, which violated common best practice.
- Kris; so examples should not violate best practice; but, best practice can be very broad, bigger than we can handle in the language  ref. topics.  Now, we have them also in arch spec, some very robust examples; I think that's where lengthy examples should go.  Many of those were added in 1.3, or relocated from lang ref.  Also, we never looked at whether we have guidelines for examples in arch spec.
- Tom; up to now, I think we simply went with 'editor's intuition' for examples in arch spec.
- Robert; well, we were a little more formal in 1.3, before that, definitely mostly intuition.  For 1.3 every common usage, and every edge case, had to be in proposal, and ended up in the spec.
- Tom; that sounds sensible.
- Nancy; end users do look at the lang ref, though not at the arch spec, and find the examples useful.
- Kris; nothing that we produce is for end users
- Tom; but in XMetal, we do show end users lang ref
- Robert; they're not help topics, but definitions
[discussion on whether we should consider the fact that end users do, in fact, have exposure to, and use, the lang ref topics, even though end users aren't our primary audience]
- Kris; I'd like to see following principles codified in writing examples for lang ref.  
1. Examples should not illustrate complexity that COULD be used; rather they should minimally illustrate the elements
2. Any example we use should illustrate either a common case or a best practice for DITA markup.
- Kris; now we need guidelines for lengthier examples in arch spec. As we have specs written by more people, we need to have more guidelines for writing them. Examples I know best are subjectscheme (which I wrote) and constraints;  I authored constraints examples because I heard complaints about how to use constraints.  Can we get a volunteer to look at examples in arch spec?
- Tom; I can pull out a summary so we can discuss them.
- Kris; thanks
***ActionItem; Tom will create a summary of examples in arch spec.
- Kris; any thoughts about longer examples in arch spec?  It's possible that some of them should be in a secondary document; maybe we should discuss later.
- Tom; so we shouldn't treat what's in there as gospel...
- Kris; we may have stuff that doesn't belong there, but in a secondary doc that talks about guidelines for constructing grammar files, because it's tutorial info.


10. Continuing item: Conformance content in the MQTT Version 5.0 (candidate) spec
    https://lists.oasis-open.org/archives/dita/201903/msg00020.html (Eberlein, 14 March 2019)
    Guidelines to Writing Conformance Clauses for OASIS Specifications (http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html), last updated 02 April 2017
    New item Terminology for DITA TC to use regarding conformance
        https://lists.oasis-open.org/archives/dita/201903/msg00039.html (Eberlein, 26 March 2019) 
- Kris; OASIS uses 3 different 'conformance' terms:
      conformance claim
      conformance clause
      conformance targets
In addition, there is the term 'normative statement', which is any statement that uses rfc-2119 words like MUST, MAY, SHOULD, MAY NOT, etc.
- Robert; we also have to deal with things like examples and appendices labelled non-normative, which implies everything else is normative.
- Kris; OASIS is not clear on this, 
- Tom; where did you get conformance definitions?
- Kris; from OASIS guidelines
- Tom; that document refers to normative content, but not normative statements; this woud be neater if OASIS's definition of conformance clause actually mentioned normative statements. 
- Kris; OASIS guidelines are pretty good, but talk about normative vs non-normative content in specs, rather than normative / non-normative stateents. OASIS does give good guidance on what they want 
- Robert; we don't need to belabor this, but need to get the language right.
- Alan; markup questions; we're wrapping terminology containg rfc-2119 keywords with ph + some @?  What is boundary of normative language?
- Kris; lwt's hold that for a little bit; it's an implementation question for 2.0.  For 1.3, we just marked up the actual RFC keyword with a DITA keyword element; no broader markup; we need to do something better for 2.0 so we can extract and publish what's needed
- Alan; good

11. Normative statements in DITA 1.3
    https://lists.oasis-open.org/archives/dita/201903/msg00036.html (Nitchie, 26 March 2019) 
- Kris; this was very helpful; gave us pretty good overwview where we have normative statements in 1.3 spec.
- Tom; this is the kind of thing we want to be able to generate from 2.0 spec?
- Kris; Chris gave us a good guide for 1.3 and how we might deal with what we need for 2.0; we should be looking at this and thinking "are there normative statements we whould be making that we're not making?" and  "are there duplicate normative statements that should be removed?"
- Chris; see our section 2.2.4.5 for a statement that shouldn't be there.
- Kris; a doc like this for 1.2 ould be cringe-worthy...
- Kris; All TC members: pls look thru Chris's conformance email and 1.3 normative statements; what's missing? what's duplicative? what's nonsensical? How should we mark them up so we can get a clean extraction to build an appendix?
- Chris; when there are topics that don't contain a normative topic, what is the purpose of the topic?
- Robert; OASIS says you only use rfc tech when you want to force something; if it's just a fact/definition, doesn't need to be normative.  Just because it doesn't have an rfc term doesn't mean it's not normative.



12 noon ET close 

        
-- Ms. Nancy Harrison

Document Name: DITA TC Meeting Minutes 2 April 2019

---

No description provided.
Download Latest Revision
Public Download Link

---

Submitter: Ms. Nancy Harrison
Group: OASIS Darwin Information Typing Architecture (DITA) TC
Folder: Meeting Notes
Date submitted: 2019-04-03 08:09:02