Groups - DITA TC Meeting Minutes 10 July 2018 uploaded

[Tom Magliery<tom.magliery@justsystems.com>]

        Submitter's message
        NOTE: There were no new action items from today's meeting.


=================================================
Minutes of the OASIS DITA TC
Tuesday, 10 July 2018
Recorded by Tom Magliery
link to agenda for this meeting:    
https://wiki.oasis-open.org/dita/Agenda-10-July-2018

10 July 2018
11 AM ET open

Roll call
Attendance: Robert Anderson, Deb Bissantz, Carsten Brennecke, Bill Burns, Kristen Eberlein, Maria Essig, Richard Hamilton, Nancy Harrison, Alan Houser, Scott Hudson, Eliot Kimber, Tom Magliery, Christopher Nitchie, Karthikeyan Rengasamy, Keith Schengili-Roberts, Dawn Stevens, Robert Thomas, Jim Tivy
Regrets: Carlos Evia, Scott Hudson

Approve minutes from previous business meeting:
26 June 2018:
https://lists.oasis-open.org/archives/dita/201807/msg00018.html (Magliery, 05 July 2018)
03 July 2018
https://lists.oasis-open.org/archives/dita/201807/msg00019.html (Harrison, 05 July 2018)
Kris: motion to approve both
Bob: second

Action items
08 May 2018:
Eric: Consider e-mail on dita-comment from Stefan Eike and report back to TC
26 June 2018:
Kris: Organize small group call with Bob, Bill, Maria, Robert, and maybe Carlos to discuss work on "DITA for Technical Content" (COMPLETED)
Robert: Review OASIS guidelines about normative statements and present at 10 July 2018 meeting
03 July 2018
Eric: Send stage one proposal to list about Stefan Eike's e-mail to DITA comment
Kris: Suggest process for harvesting best practices and tutorial information that is removed from topics as part of element-reference reorg (COMPLETED)
Kris: Schedule additional discussion about "Specialization hierarchy" section and audience for examples (COMPLETED)
[Noted that Eric's item for 08 May was completed last week, left on the agenda by mistake]

Spec editing report
...
NEW: Examples of reworked navtitle topics
https://lists.oasis-open.org/archives/dita/201807/msg00013.html (Eberlein, 04 July 2018)
Kris: I sent examples to the list during the last week.
[We took time to review the PDF during the meeting]
Bob: Thanks, this makes things more concrete.
Kris: We're trying to make things more clear with examples.
...
New: Discussion about "Specialization hierarchy" and "Example" section
How will folks know whether base elements are defined in topic or map?
Do we need to keep the value of the @class attribute?
https://lists.oasis-open.org/archives/dita/201807/msg00009.html (Thomas, 03 July 2018)
Kris: Nancy raised the point before about how people will know if something is defined in topic or map module if we don't have any specialization hierarchy. Others commented they wanted to keep the @class attribute.
Bob: My email pretty much speaks for itself, it's pretty much as easy to include the class hierarchy as it is to leave it out.
Robert: I have come to dislike the class hierarchy after all these years, started to question it when I found many that were wrong. I was surprised at how many. Also we have so many people reading our spec who expect it to be more of a user document, and this is one of those things that gives DITA the impression of being complicated, makes people think it's an ugly hack. That's why I don't like it, although I won't fight to exclude.
Alan: So someone who is implementing specializations should use the grammar files?
Robert: Yes, the way I've always done it is to copy the element I'm changing and make the changes. So yes, you have to be in the grammar file anyway.
Alan: And it can't be wrong in the grammar file.
Bob: I am swayed by this argument. Certainly the description of @class is going to explain its role anyway.
Kris: I confess I've never gone here in the element reference for this. I always get it from the grammar files.
Tom: I see these points, but I'm not 100% convinced these should be removed
Chris: Ditto
Nancy: It can be useful to writers
Robert: Only once they know what it means
Chris: When I've generated -- generated! -- descriptions of specializations from the grammar files, what it will show is a nested list with the specialization ancestor as a parent and anything generated as child nodes, and that worked really well. That said, talk about a Q/A nightmare to have it in the spec. It can only work as generated, not edited.
Kris: Just a reality check: we're not talking about omitting natural language, just talking about whether to include class attributes in addition.
Nancy: will the natural language indicate the class hierarchy? Or just the top level element?
Bob: I would assume all the ancestors
Kris: One example here would be glossentry, spec from concept, spec from topic
Alan: Wouldn't the closest specialized ancestor be useful?
Robert: You definitely need to know it comes from concept
Nancy: You need to get to top
Tom: Why?
Bill: I'm more concerned with the constraints from the previous level
Robert: How many cases of multiple levels do we have? Do we have any others? Maybe in L&T? I guess learning bookmap. I don't think we have clearly established why and when we look for this info.
Kris: We're getting a little bit astray since this won't affect the base spec. It will affect DITA for techcomm (or whatever we call it)
Bob: I think I'll withdraw my email about this.
Robert: These could be generated as a standalone document or a section in a document.
Tom: A generated appendix might be useful.
Kris: It's good to get things out of the topics that is difficut to Q/A.
Robert: I've gotten complaints about this from people before.
Nancy: Having an explanation of what this information means would be useful for people.
Kris: I think we are near a consensus to have the natural language as well as an appendix with some information what the class attributes are.
Bob: I think this information would make more sense in an artifact that discusses content models.
Robert: I could be convinced to have this as an appendix, but maybe not the content models. We get complaints about the length of the spec.
Kris: Consensus: moving the class attr information out of element reference topics, but not fully decided where we will put it. Could be a non-normative appendix, or could be an ancillary document. We don't have automated processes to either generate the content models or the contents of the class attribute, although I suspect Chris N could provide that easily.
Nancy: It would be useful for us to make a decision in the next few weeks. If there are others with ideas they should speak up soon. I'd like to see this discussion continued.

Who is the audience for the examples in the element-reference topic? What should the examples illustrate?
Kris: Who really is the audience for examples in the spec topics, and what should they illustrate? I indicated my own sense earlier by saying they should illustrate processing expectations, info to put in usage info or how to use complicated attributes to show how to do something with an element. Any discussion? Note: by definition all of our examples are non-normative.
Robert: The spec 1.0 examples really just tried to give an example of every element with no purpose behind it. Since then in 1.1 I sort of followed that to start with, though I tried to use some possible usage, then additional examples to show every edge case we've described. But that's not consistent with 1.0 and it's not stated anywhere that we're doing it. We have never defined an audience for the examples.
Kris: Where I come from when I have reworked these examples, it's tough, because we have no audience, they're not normative, we know they're read by non-developers.
Robert: I think I've inconsistently tried to work for both tech and non-tech audiences. If there's some peculiar usage I'll write an example for an intended author. Sometimes if there are challenging processing rules I'll write an example for developers. So those are both in there. I kinda think both are defensible.
Tom: Does it make sense to put the examples closer to the text that matters, either the processing info or user info?
Bob: I would agree if this were a user manual, but this isn't
Kris: Right, this is a spec. It's a challenge to have this information spread around, some people don't even want ANY examples in the spec.
Bob: Back to who is the audience, that ambiguity could be mentioned in each example who it's for.
Tom: That's an idea to remember as a possibility.
Kris: Every codeblock has a comment like that, why it's there, who it's for. I think we need to keep an eye on examples as we rework them until we have enough information for clear guidance.
Kris: So this is another area we need to have more discussion later.

Subcommittees and Adoption TC

Report from Learning and Training subcommittee: 10 July 20018
Dawn: Kris suggested we start with the L&T files and start cleaning them up for having it as a separate spec. From that advice we had a discussion where we said that could result in greater work for us because there are some things we want to do but don't want to touch these files. E.g. the assessment2 series of elements -- we know we want to make those elements the standard model and get rid of the original ones but get rid of all the 2's. So we have work to do to clean all this up and save copying so many files. Overall we made a list of work to do, need to submit to this group. Then we will do those things in concert with the cleanup of the rest of the spec. Another thing we're considering is removing the entire learning-plan section from the spec; we know of no one using it, and it's perhaps 1/4 of the spec. We're going to work on this to-do list and bring it to the TC for blessing. We also talked about whether there's anything new and critical, such as the context-less topic type that we have discussed here in the TC. I probably will be the sponsor of that here in the TC.
Kris: I don't think you need TC approval for removing all the deprecated domains, or the 25% of unused stuff in the spec.
Kris: Do people want these sorts of things in the TC, or just in these monthly reports?
Tom: I'm happy to see these in the monthly reports.
Alan: agree
[Otherwise silence, assumed assent]
Dawn: We will be meeting again today and starting this work.
Kris: Robert can you assign the context-less topic item in github to Dawn.

DITA 1.3 Errata 02
Status?
21 June 2018: Opened request for OASIS to publish
03 July 2018: Asked OASIS for a time estimate
06 July 2018: PUBLISHED! YEAH!
https://lists.oasis-open.org/archives/dita/201807/msg00018.html (Chet Ensign, 06 July 2018)
Kris: Let's hope we don't have to do an Errata 03!

DITA for Technical Content
Action items:
New name for this work product?
https://lists.oasis-open.org/archives/dita/201807/msg00005.html (Burns, 03 July 2018)
https://lists.oasis-open.org/archives/dita/201807/msg00006.html (Thomas, 03 July 2018)
https://lists.oasis-open.org/archives/dita/201807/msg00007.html (Houser, 03 July 2018)
https://lists.oasis-open.org/archives/dita/201807/msg00008.html (Hudson, 10 July 2018)
Small working group scheduled to meet 11 July 2018, 1-2 PM ET

Kris: We'll start work with the items that are listed here in the agenda.
Kris: What do we think is the best name for this work product? Where did we leave that last week?
Kris: I think there was a suggestion for DITA for Technical Communication. Chris suggested this is a catch-all topic, some are specific to software/tech docs, but we also have the very general and useful concept, task and reference
Chris: Yes, I question whether it might actually be two separate things.
Kris: can you elaborate on that?
Chris: Maybe we need multiple packages. It's not strictly for tech docs people ... except when it is. The software etc. domains are very specific and have very limited applicability outside those fields. Whereas the structural elements have much more use in all areas of expertise, general applicability. I think it's right not to consider them base, but DITA users who do not make use of those things will be vanishingly rare. Especially when we're looking to broaden the audience for DITA. I think tying these two things into a single package will continue to lead people down the path of thinking DITA is for tech docs because look at all this crap here.
Bob: So do you think the domains should be handled separately?
Chris: It's not quite so clean, there are some domains that are still useful generally. It's a bit of a fuzzy line. Although programming, UI, software are VERY software specific. I'm sensitive to the fact that this doubles the overhead of this enterprise. But if 2.0 is a chance to fix things broken, this is a good one to consider.
Bob: when I think of tech comm I don't equate this with programming. I think of it as prose, it can easily be about other things than software.
Tom: I like the idea of splitting this, trying to find a place to draw that fuzzy line, although it will be fraught with afterthought, with people wondering why this or that is not in the "other" part.

12 noon ET close
        
-- Mr. Tom Magliery

Document Name: DITA TC Meeting Minutes 10 July 2018

---

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: 2018-07-10 15:25:10