Re: [dita] Groups - DITA TC Meeting Minutes 28 May 2019 uploaded

Adding attendance for the meeting:

    
      
Zoe Lawson

      
Dawn Stevens

      
Kris Eberlein

      
Bill Burns

      
Robert Anderson

      
Stan Doherty

      
Nancy Harrison

      
Eliot Kimber

      
Keith Schengili-Roberts

      
Tom Magliery

      
Chris Nitchie

      
Carsten Brennecke

      
Scott Hudson

      
Carlos Evia

      
Deb Bissantz

      
Joyce Lam

      
Jim Tivy

      

    
    
Best,

      Kris

      

      Kristen James Eberlein

      Chair, OASIS DITA Technical Committee

      Principal consultant, Eberlein Consulting

      www.eberleinconsulting.com

      +1 919 622-1501; kriseberlein (skype)

      

    

    
On 5/31/2019 5:06 PM, Tom Magliery
      wrote:

    

    
      
      Submitter's message

      New action items:

      - Kris and Robert to revise this content and run it by Eliot
      (Draft-comment in spec WD03, section 3.3.3, page 37)

      - Robert to take an initial look at fixing this (Draft-comment in
      spec WD03, section 3.4.4, page 52)

      - Chris N to look at draft-comment in spec WD03, section 8.2.2.19,
      page 210

      

      

      =================================================

      Minutes of the OASIS DITA TC

      Tuesday, 28 May 2019

      Recorded by Tom Magliery

      link to agenda for this meeting:

      https://wiki.oasis-open.org/dita/Agenda-28-May-2018

      

      11 AM ET open

      

      Attendance:

      (TBA)

      

      Business

      ========

      1. Roll call

      Regrets: Eric Sirois, Alan Houser

      

      2. Approve minutes from previous business meeting:

      

      14 May 2019

      https://lists.oasis-open.org/archives/dita/201905/msg00043.html
      (Harrison, 16 May 2019)

      Moved by Kris, 2nd by Bill, approved by TC

      

      3. Announcements: none

      

      4. Action items review

      

      13 November 2018

      Eliot: Test refactoring of grammar files; due 21 May

      18 December 2018

      Eliot: Investigate issue re
      earningAggregationsTopicrefConstraintMod.xsd; due 21 May

      

      Pushed these two items back to end of June.

      

      

      5. DITA 2.0 editorial work

      Highlights?

      See Editorial work completed for a full summary

      Working draft 03:
      https://lists.oasis-open.org/archives/dita/201905/msg00056.html

      

      [Screen sharing of Working Draft 03]

      Kris: several sections edited, some Stage 3 proposals integrated,
      and markup overhauled for all RFC 2119 statements

      I've been uploading a new draft every Friday, now on version 3. v1
      had a reworked TOC, removed an old arch spec heading level to
      reduce nesting. v2 introduced some styling for in-body normative
      statements. v3 introduced a new non-normative appendix showing all
      the RFC 2119 statements.

      Robert: (showed TOC in screen sharing) (showed styling of
      normative statements in the body of the spec) This styling may not
      be what we will have in the final spec, but at least it will be
      easily visible during reviews.

      Kris: I think it would be nice to have some kind of styling in our
      final draft, although this might look a bit like revision bars.

      Scott: I can see the concern about change bars. What about a
      note-like icon?

      Kris: Another thing is we could add top/bottom borders.

      Kris: We can do anything that we could do to style an fo-block

      Eliot: I'd like to see a reference to the rule # in the appendix

      Robert: I expect that to come

      Eliot: That could also work as the icon

      Nancy: Could we use a different character instead of a vertical
      line?

      Robert: We may be limited by xsl-fo on that point. We have run
      into that at IBM.

      Robert: I do expect to have all of these rules numbered eventually

      (showed appendix of collected RFC 2119 statements)

      Robert: Again this is a first, rough draft, don't expect the spec
      to look exactly like this

      Robert: This is an automated collection of all the normative
      statements in the draft

      Robert: This is already allowing me to see some things that
      probably shouldn't be normative statements

      Kris: It's also highlighting some things that we repeat
      normatively that we probably should have only once

      Tom: Are we going to have a review any time soon that will include
      the normative statements?

      Robert: Difficult to say. Reviewing them entails reviewing the
      entire spec.

      Kris: We have some challenges here. Our big issue is we
      potentially make some normative statements that we shouldn't be.
      There are also significant areas about DITA where we are NOT
      making normative statements. Those are really hard to discern.

      Tom: Should we have a review focused on normative statements?

      Kris: We have an open action item for everyone to do that already,
      since Chris first pulled them all together. I want to encourage
      everyone to do that.

      Kris: Another thing is, every week we're going to ask TC embers to
      review some draft-comments. The new ones in today's draft are
      almost all about normative statements. So that may be another way
      we get at some of this.

      Robert: It's always hard to spot absences, but if something is a
      core part of DITA that doesn't mean we need a normative statement.
      If something simply "is", that doesn't mean we need a "must" sort
      of statement, it's simply a fact. E.g. there's no need to have a
      normative statement that says a topic must have a title; the DTDs
      already enforce that.

      

      

      Kris: Let's move on to a review of draft comments

      Robert (scrolls to first draft-comment in spec draft, page 37,
      section 3.3.3)

      Kris: Should this be normative?

      Eliot: Either it should be stated in a direct way, in terms of the
      precedence of the source of the value rather than how a processor
      might work, that is the processing should be implicit in the
      rules. But if this behaviour is already implicit in the rules than
      there should be a non-normative note (if it's here at all).

      Kris: I don't know whether what we're stating here is already
      normatively stated in how our processes handle values for DITA
      attributes.

      Robert: I don't think this is stated elsewhere.

      Robert: So Eliot what you're saying is this intro clause should be
      something like "The effective value for a DITA attribute IS..."

      Eliot: Yes, it should be declarative not procedural

      Kris: So we need to change the introductory sentence

      Eliot: I have a concern, which is that this also affects cascading
      values of attributes in maps. We need to be careful we're not
      restating this rule.

      Eliot: Also in this list, items 1&2 come from XML behavior,
      it's not until #3 that we get to things that are needed for DITA

      Robert: The editors need to make sure this content is not
      duplicated. We can't just delete it because we lose the part about
      defaultSubject

      Eliot: The list altogether is good, but perhaps there needs to be
      another statement that says that these rules apply when cascading
      is needed.

      Kris: This was something we introduced in DITA 1.3. 

      Eliot: I think the previous paragraph "The default attribute
      values ..." could maybe be the normative statement

      Robert: That's probably correct

      Eliot: Then what follows is a nice explantory note

      ACTION: Kris and Robert to revise this content and run it by Eliot

      

      

      Next draft comment: (page 52 in section 3.4.4)

      Kris: This one is self-evident

      ACTION: Robert to take an initial look at fixing this

      Robert: This probably needs the same reworking that Eliot
      mentioned earlier

      Robert: Maybe defaultSubject should be added here, maybe between
      steps 9 and 10

      

      

      Next (Section 6.4.4, page 150)

      Kris: A five-year-old comment! We can finally address this,
      because it will no longer potentially create backwards
      incompatibility

      Kris: any objections to the change?

      (no objections raised)

      

      

      Next (Section 8.2.2.19, page 210)

      Kris: This may not be a matter for whole-TC discussion. We'll pass
      on this for now

      ACTION: Chris N to look at it

      

      Next (Section 8.2.2.22, page 213)

      Kris: We put all statements about formatting into an appendix. We
      do make some normative statements about rendering, although we
      don't use "must" statements, but we decided there are some places
      for "should" statements

      Eliot: I forget our distinction between "formatting" and
      "rendering"

      Kris: Formatting being strictly styling per se, rendering falling
      more in the example of is particular content exposed or not
      exposed. Are there fallback mechanisms. It's a hazy grey area.

      Eliot: I think the word "preserved" is problematic. It would be
      better to just mention that they are rendered in some way. E.g.
      poetry can use slashes.

      Robert: agree

      Kris: This is exactly the kind of discussion we should have about
      many of these topics, some of which have been around since DITA
      1.0

      Kris: Suggested wording: Line breaks are preserved or otherwise
      represented.

      We can massage the wording

      Eliot: I would be more direct, not have a list, but just a
      statement, "Processors should do this and that"

      Robert: the critical part to call out here is the line breaks, not
      the white space.

      Robert: I'm picturing this now as a paragraph that SHOULDs the
      line breaks, and another note about the white space is just
      informative

      

      

      6. Stylesheets

      Update

      Work merged in GitHub

      Open items that need fixes

      Work in development

      See https://wiki.oasis-open.org/dita/stylesheetBacklog

      

      (screen-sharing of backlog)

      Kris: We have two things currently broken in the style sheets -
      cross refs (broken in DITA OT) and indentation for shortdesc and
      related links is not being rendered correctly. But you've seen
      results of the biggest recent changes to style sheets. We'll
      continue to work forward. Currently the numbering in the PDF comes
      directly out of templates in that plugin. But we want the
      numbering for all of our spec outputs to come from a single
      ordering plugin to ensure consistency across output formats.

      Robert: That actually is what blocked me from getting numbers in
      the appendix of normative statements. I don't want to implment
      that twice for HTML and PDF.

      

      

      7. Show-and-tell of how normative statements in spec are now
      rendered

      Working draft 03:
      https://lists.oasis-open.org/archives/dita/201905/msg00056.html

      Normative instances in body text

      (Non-normative) Aggregated in an appendix

      Discussion

      

      [We covered this under another item above]

      

      

      8. Draft comments in latest working draft from TC attention

      We will review and discuss them

      Working draft 03:
      https://lists.oasis-open.org/archives/dita/201905/msg00056.html

      

      [We covered this item out-of-order earlier in the meeting]

      

      

      9. Name of spec that contains CTR etc

      Technical Content versus Technical Communication? Something else?

      https://lists.oasis-open.org/archives/dita/201905/msg00048.html
      (Eberlein, 19 May 2019)

      Lots of responses ...
      https://lists.oasis-open.org/archives/dita/201905/msg00052.html
      (Evia, 21 May 2019)

      

      Kris: What shall we call our release that contains CTR, bookmap,
      glossary, all of the related domains? Do we call it Technical
      Content, Technical Communication? After the polling in the group,
      is there anything better than Technical Content? Glossary is a
      feature that is more generic than technical content.

      Kris: Carlos what were your reasons for not using Technical
      Communication?

      Carlos: It goes against the efforts I make to tell people what
      this spec is broadly useful for.

      Kris: We don't have to decide this today but we do need to decide
      this in fairly short order for OASIS process purposes

      Robert: Carlos's comment makes sense to me from what I've heard in
      industry. "Tech Comm" is so broad that trying to use that here
      seems wrong. "Technical Content" seems off a little, too.

      Carlos: If this were 1995 we could say "documentation" but it
      isn't

      Eliot: Aren't we really talking about hardware/software
      documentation when we talk about CTR? The two domains +
      troubleshooting stuff? But I guess that leaves out
      machineindustry?

      Robert: that's kind of hardware

      Kris: How about DITA for Technical Documentation?

      Scott: Even doc has kind of a print sound as opposed to "content"

      Carlos: The thing is "content" is now a more granular kind of
      thing. 

      Tom: Maybe we need a term that gets away from the word "Technical"

      Eliot: Maybe "task-oriented content"? Really much of this kind of
      content is driven by tasks

      Deb: Medical content is often very conceptual

      Bill: Ours, too

      Zoe: What's difficult is in my brain DITA is CTR so calling out
      that part as something different from DITA hurts my brain

      Kris: This is something we all need to mull over. In 1.3 we really
      began to emphasize that the real building blocks of DITA are topic
      and map and that the others such as CTR are about more specific
      use cases

      Chris: What we traditionally called technical conteng is a
      conflation of CTR that are not technical in a series of domains
      that are profoundly technical. Finding an umbrella is challenging.
      Long thought it would be valuable to split them up, but there are
      logistical barriers.

      

      Kris: people please take a look at the PDFs (DITA 2 working draft
      03 and also the "to be named 2.0" under item 10 below)

      

      

      10. DITA for 'To be named' version 2.0

      

      Update on editorial work completed

      Working draft 01:
      https://lists.oasis-open.org/archives/dita/201905/msg00047.html
      (Eberlein, 19 May 2019)

      

      Work to be done:
      https://wiki.oasis-open.org/dita/ditaTechnicalContent2.0backLog

      

      

      12 noon ET close

      

      

      -- Mr. Tom Magliery
      
        
          

             Document Name:
              DITA TC Meeting Minutes 28 May
                2019

               No
              description provided. 

              Download Latest Revision

              Public Download Link

               Submitter:
              Mr. Tom Magliery

              Group: OASIS Darwin Information Typing
              Architecture (DITA) TC

              Folder: Meeting Notes

              Date submitted: 2019-05-31 14:06:24