OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Groups - DITA TC Meeting Minutes 28 May 2019 uploaded

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, page 210

Minutes of the OASIS DITA TC
Tuesday, 28 May 2019
Recorded by Tom Magliery
link to agenda for this meeting:

11 AM ET open


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
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, 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, 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
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

[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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]