Submitter's message NOTE: please review the list of volunteers and associated topics to make sure I recorded this info correctly; let me and Kris know if your name is included, or omitted, by mistake,
Thanks,
Nancy
ActionItems:
1. Kris and Robert will look at how they broke down @s in the wiki page table listing what needed to be reviewed, to see if that's a way to make progress, and to see if we can review them in smaller subsets,
2. Kris will look at latest OASIS directives for conformance statements.
y===============================================
Minutes of the OASIS DITA TC
Tuesday, 4 February 2025
Recorded by Nancy Harrison
link to agenda for this meeting:
https://github.com/oasis-tcs/dita/wiki/Previous-agendas
Attendance:
===========
Robert Anderson, Stan Doherty, Kris Eberlein, Nancy Harrison, Bob Johnson, Eliot Kimber, Zoe Lawson, Christina Rothwell, Eric Sirois, Dawn Stevens, Frank Wegmann, Leo Belchikov
Business
========
Regrets: none
1. Approve minutes from previous business meeting
14 January 2025 (Harrison, 15 January 2024)
https://groups.oasis-open.org/discussion/dita-tc-meeting-minutes-14-january-2025-uploaded
Kris moved, 2nd by Dawn, approved by TC
2. Announcements:
- Dawn; everything looking good for DITA Europe, but because it's not in Finland, we won't be getting entire staff of the major Finnish DITA client to come.
- Robert; not much news on DITA Open, but should be a good show.
3. Review of base spec sections
https://github.com/oasis-tcs/dita/wiki/DITA-2.0-base-specification-work
- Kris; As we discussed last time, we need for people to look through and make suggestions for things to be done. Some will be really granular, some are not, e.g. the key-based addressing section has a lot of topics and nested content, with over a dozen core arch topics plus large examples of keys and keyscopes. So we might want to break that down if we're asking folk to do this.
- Robert; that section includes 2 big sections of excamples. We might want to make one review section for scoped content, and one for content not on scoped keys. For 1.3, key stuff was our most reviewed stuff, so it's a better base than e.g., branch filtering.
- Kris; good point, might be less laborious than it might look
- Robert; for example, changes in keys for 2.0 are much less than e.g. conref was, where we made huge 2.0 changes. Keys are complex, but you shouldn't be scared just from the amount of content.
- Kris; so how should we break it up for initial review?
- Robert; I'd suggest key scopes and not key scopes? OTOH, no matter how well it's already done, it's still a lot of content
- Zoe; keys are awesome and powerful and also scary, we might want two reviewers , one expert, oneless expert; I volunteer for the 'less expert' role.
- Robert; that makes sense
- Zoe; willing to be a novice reviewer
- Stan; I'm with Zoe, as a 'less expert' reviewer.
- Bob; a common use of keys is as variables, does this section address that?
- Robert; yes, it does.
- Kris; wrt two reviewers, primary audience is developers, the spec is not a user guide. OTOH, plainer language is good, wrt larger outline,
- Kris; Another place that needs a lot of attention is attributes. This section is full of notes like '[topic to be moved to another location]' or '[determining effective attribute values]' that are just placeholders. It's the same for DITA maps and their usage, they're just a list of stuff, We don't want normative content in examples, but need to lay out what's happening in maps in clear architectural topics.
- Robert; and a lot of this is new work, but we'd really like to get it done, since it's content that should have been there since 1.x. It would be disappointing to not have it here at 2.0.
- Kris; Ideally, we would have new topics for these.
- Zoe; I'm willing to help, but afraid any content I added might end up 'user guide-ish'.
- Robert; as it happens, an overview of this stuff, which is what's missing, is the closest the spec would be likely to come to having a 'user guide' feel, even if it needs to be more technical.
- Bob; so you're asking for vounteers?
- Kris; yes, we need a read thru of existing sections to point out what's problematic, so we can get closer to opening up work.
- Christine; sounds good; I would also be leaning towards user guide type of content.
- Kris; we need to balance off that with more technically expert reviewers to do initial read-thrus of this sections.
- Stan; so a two-pass process.
- Kris; so volunteers?
- Frank; what's the time frame? I'm fully booked this month, will get better in March
Volunteer offers:
- DITA maps and notation: Stan and Zoe
- @id attribute: Frank and Bob
- uri-based direct addressing: Stan and Christine
- indirect key-based addressing:
o Eric keys and scoped keys
o Zoe for non-scoped keys
- context hooks for user assistance: Stan
- navigation; Frank and Eliot
- conditional processing: Nancy
- branch filtering; Eliot and stan
- DITAVAL ref domain:
o connected to branch filtering, so Eliot and Stan
- Kris; wrt DITA processing, didn't we already do navigation?
- Robert; yes, we did.
- Kris; no, it actually turns out we didn't . And for now, we'll skip over 'Determining efective attribute values'
- Robert; I don't think we should do attributes right now, that content will be impacted by branch filtering.
- Kris; some of the attributes got reviewed as part of targeted reviews; recorded in some old wiki pages, Robert and I should look at how we broke down @s in that table to see if that's a way to make progress
- Robert; ok
***ActionItem: Kris and Robert will look at attribute lists in old wiki page to see what makes sense, and if we can review them in smaller subsets; some are, in fact, ready for review. A lot of places where they need work is link-relationship @s, the content hasn't changed since 1.0, and so the wording isn't as precise as we now need.
- Kris; last item in base spec is conformance, we started work on this long ago, made a start but got no farther; I'd want to hear from Eliot and Robert on these.
- Robert; too long since I looked at it, I'd have to go thru it again.
- Kris; could you look at it and say what needs to be done on it?
- Eliot; conformance hasn't changed from 1.3 to 2.0
- Robert; at 1.3, we thought we should get rid of rules about conforming shell, e.g. order of stuff in shells, I don't remember if we got rid of that.
- Eliot; I might have removed them.
- Kris; there's a difference between actual conformance statement, which we punted on, and our normative statements in body of spec; we relaxed them around what you must do in doc shells,
- Robert; so we just need to remove use of 'non-comforming' as description of a DITA doc.
- Kris; maybe we need to return to 1.3 for what shoud be in 2.0 conformance topice.
- Eliot; I don't think we should need to change much,
***AI: Kris will look at latest directives for conformance statements, memory is that 1.3 was first spec to have a conformance statement, OASIS had requirements, but we couldn't do them in a point release.
- Robert; I think the 2.0 layout came from OASIS requirements.
- Kris; we need to ID actual arch features that are critical for conformance. The the first list would be of the features that have to be handled by an implementation for it to be DITA-conforming. Those would be the features that have important mornative rules associated with them.
- Robert; so it's more of a checklist for what you need to have in your implementation.
- Kris; we'll need to do a compaison between 1.3 and 2.0 in this section. So, what are we asking people to do?
- Robert; go thru their topics to find content that's either clearly wrong or hard to understand; that way, Kris and I can discuss it, and fix it, before it goes to review. That would include typos and that kind of stuff, but also general feedback like 'does this make sense'? For example, a comment like 'this topic was moved and needs an update'. We also need to include a review of organization in your consideration of topics; should the topics you're looking at be re-organized?
- Stan; so do we need to test examples, or just review them?
[unanswered query?]
11:58am ET close
-- Ms. Nancy Harrison
---------------------------------
Nancy Harrison
Principal, Infobridge Solutions
Nancy Harrison (Personal)
Portland OR
978-505-9189
---------------------------------