|
Tom, just a few corrections; thanks for getting the minutes out
so quickly! See inline blue bold
below
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
On 7/12/2016 8:24 PM, Tom Magliery
wrote:
Submitter's message
New Action Items Summary:
1. Folks to review revised content-model sections of the
specification following Robert's cleanup. Tom will look at
all-inclusive, Deb & Maria at tech-comm, Robert at base. There
is some urgency to this item as Robert will soon be on vacation
for two weeks.
2. Eliot to make two changes to mathmlDomainProxy.rng in the
errata; one regarding public ID and another involving some
refactoring. Take care to follow tracking procedures carefully
(see Kris and Robert).
3. Eliot to add missing entries in base/catalog.xml.
4. Eliot to update the two learning map DTD and XSD to match the
RNG files.
5. Robert to add item to the 1.3 errata wiki page regarding
task/machinery task body constraints.
=================================================
Minutes of the OASIS DITA TC
Tuesday, 28 June 2016
Recorded by Tom Magliery
link to agenda for this meeting:
https://wiki.oasis-open.org/dita/PreviousAgendas
Standing Business
=================
Approve minutes from previous business meeting:
Motion to approve by Kris, seconded by Dick, approved by
consensus
Subcommittee Reports
====================
None
Business
========
1. Action items:
----------------
7 June 2016: Michael: Post link to slide share of Webinar (sent
to incomplete list, will do ASAP)
21 June 2016: Kris, Nancy, Bob: Meet about documenting errata
items and errata builds (Bob and Kris will meet with Nancy soon)
All other action items completed.
2. Announcements:
-----------------
Results of ballot for OASIS Board of Directors posted by Kris.
3. Continuing item: DITA 1.3 errata
-----------------------------------
https://wiki.oasis-open.org/dita/DITA%201.3%20Errata
Item to consider this week: testing the new content model
topics.
Robert: This is mostly a sanity check -- look for strange stuff.
Don't need to go through doctypes to check for full correctness.
We're comfortable enough that they're accurate at that level.
Issues for now are more like things appearing 2,3,4, or many
times more than they should. E.g. formerly the content model for
ditavalref said you could insert some element 5 times but it
should only have appeared once. Best way to review is to scroll
through the topics and see the "Contains" to see if the model
looks valid based on what you know and the syntax used for those
tables. Could bring up the published 1.3 spec in one window and
the new topics in another window. Chris N. will send links to
new Titania versions for people to read.
[ACTION] Tom will look at all-inclusive, Deb & Maria at
tech-comm, Robert at base. There is some urgency to this item as
Robert will soon be on vacation for two weeks.
4. Continuing item: More Catalog Errata: Public ID for RNG
MathML Module
------------------------------------------------------------------------
https://lists.oasis-open.org/archives/dita/201606/msg00009.html
(Kimber, 9 June 2016)
https://lists.oasis-open.org/archives/dita/201606/msg00010.html
(Kimber, 9 June 2016)
https://lists.oasis-open.org/archives/dita/201606/msg00016.html
(Kimber, 15 June 2016)
Eliot: There are two parts to this: 1. Add the public ID for
mathmlDomainProxy.rng file, which never got one before. 2.
Redefine the content of that module in a way that allows it to
be used by any shell. As it's currently defined, for any new
shell that reflects a specialized topic type that integrates
MathML, you would need to update your own copy of
mathmlDomainProxy.rng, obviously a bad thing. Worked out a way
to define the proxy file in RNG so that's not required.
Kris: any questions/concerns with making these changes?
[silence]
TC agrees that Eliot should move ahead with these changes
[ACTION] Eliot to make the changes in the errata.
Kris: We need to keep very fine track of any changes we make,
whether it is to a spec topic, catalog file, grammar files, etc.
Need to summarize the changes, original text vs. new text, etc.
Keep in touch with me and Robert regarding how to track the
changes.
5. New item: xml.xsd and ditaarch.xsd in catalog.xml for DITA
1.3
-----------------------------------------------------------------
https://lists.oasis-open.org/archives/dita/201607/msg00013.html
(Frederik Geers, 7 July 2016)
Kris: Eric have you looked at this?
Eric: Saw there's two missing entries. They should be there.
Kris: Is this something we can handle as an errata?
Eric: Yes, I think so.
Kris: We just have some missing URI entries.
Eric: Xerces uses system IDs anyway; otherwise we'd be noticing
issues.
Kris: Does anyone have concerns with these changes being made
for these catalog files?
Eliot: No, these entries are simply missing.
Kris: Who should have action item for this? Eliot do you want to
take it?
Eliot: happy to take it
[ACTION] Eliot to add missing entries in
base/catalog.xml.
6. Continued item: Problem with learningObjectMap,
learningGroupMap DTDs
------------------------------------------------------------------------
https://lists.oasis-open.org/archives/dita/201606/msg00066.html
(Anderson, 29 June 2016)
Kris: Based on discussion last week, any suggestions as to
what to do here?
Robert: I don't want to make the decision here. I don't use
this doctype. Options previously mentioned are 1. leaving it
as-is; 2. expanding the RNG so it matches DTD & XSD; 3.
restricting DTD and XSD to match the RNG)
Kris: options 2 and 3 potentially are substantive
changes Option 2 would be a substantive change.
Kris: It may be better to break existing documents now than go
ahead for 5 years with DTD and XSD incorrect.
Kris: The other option is to let things stand as they are,
allowing DTD and XSD to stand as they are, but provide updated
constraint modules for updated XSD shell so these shells could
be used correctly
Robert: That might be the way to go IF we knew that RNG would
be correct in 2.0
Eliot: use of a constraint in a shell is sort of optional;
base content model is more open. Trying to remember what
intent of constraint was.
Kris: The intent was to disallow topicheads topicrefs.
Robert: It turns out turning off
topicheads topicrefs
turns off any ability to reference individual topics
Eliot: The point of these map types was to be very narrow in
their focus. There's no sense in which learnging group map and
learning object map are general maps. These two designs came
from the guys at SAP.
Robert: I thought that John Hunt thought that these might not
be strictly necessary, but SAP wanted them.
Eliot: given current level of adoption, would not be worried
about correcting the DTDs and XSDs
Bob: in favor of fixing the DTD because if we don't it remains
an error.
Kris: Bob is speaking for my preference as well. These are not
map types I understood, but for whatever reason we let them
become part of the spec, and the RNG version is correct
(normative) so we should fix the DTD/XSD to match.
[brief side debate about whether document type shells in the
spec are normative]
Kris: We do have the issue that whatever changes we make for
the errata have to be non-substantive. The real point in
question here is what do we want to do regarding these two
particular map types in DTD and XSD forms.
Eliot: RNG is normative; if DTDs and XSDs do not reflect that,
then they are an error. It can't be considered a substantive
change to correct the DTDs and XSDs to reflect that.
Kris: Similarly we cannot relax the RNG. So there are two
choices: Fix the DTD/XSD, or let them stand as-is and
conceivably update the DTD constraint module or XSD shell for
users who want a more constrained content model
Eliot: It makes more sense just to fix them
Kris: Does anyone want to advocate an alternate position to
fixing the DTD/XSD?
[silence]
We have muted consensus to move ahead
Kris: This action will require an elaborate constraint on the
DTD side
Robert: One issue I see is that per DTD rules it will reuqire
two constraint modules. This brings up an oddity that in
XSD/RNG it is a single domains token, but in DTD it will be
two domains tokens.
Eliot: Conceptually it's only one, eliminiating these 4 things
from the map group. It's just being manifested in 2 places
Robert: I think if following the coding rules these are two
separate constraints, requires two tokens. It's weird but
that's a topic for another day.
[ACTION] Eliot: Update the DTD and XSD to match the RNG files.
Kris: again please interact with Kris and Robert re: the
errata change log. Note that this is the first change to
catalogs and grammar files we've had in the 1.3 errata.
7. Continued item: Issues noticed with taskbody content model
in various task types
-----------------------------------------------------------------------------------
https://lists.oasis-open.org/archives/dita/201607/msg00005.html (1 July
2016)
https://lists.oasis-open.org/archives/dita/201607/msg00007.html (3 July
2016)
https://lists.oasis-open.org/archives/dita/201607/msg00008.html (3 July
2016)
Robert: There are not too many options here based on
discussions had elsewhere
The machinery task was overlooked when implementing the
troubleshooting task; machinery has a constraint that does not
allow new elements, and was not updated to allow it.
Whether you consider constraints normative does not apply
because we have normative text in the architectural spec that
says in effect "we have this [troubleshooting] in task body".
For the errata we need to update the architectural spec to say
that this stuff is allowed for task and general task
Kris: We need to leave machinery task as it stands although we
could document an example updating the machine industry task
body constraint to incorporate task troubleshooting. We could
do that as an example topic or somehwere in the errata. But we
can't actually modify the constraint itself.
The content model for general task and strict task shell are
correct, they do permit task troubleshooting.
There are some spec topics specifically the tech comm types
that do not mention troubleshooting, and these toipcs were not
updated to mention them
Kris: Generally for 2.0 we want to reconsider whether we have
conceptual topics that mention these things.
For the errata we want to update these toipcs to ensure that
they mention them all
With appropriate constraints for stict task body
We cannot change the costraint for machienery task
We can say "the TC goofed here, we forgot to update this
constraint".
Eliot: looking at the constraint, I'm not sure this constraint
is wrong
Robert: it's a new task element
Robert: the only open question is whether we put an additional
example of some sort in the spec
I'm skeptical that it would be found and used but this doesn't
mean we shouldn't put it in
Kris: I did post on the dita-users list for how many people
were using machinery task. [One person replied so far.]
Amber: I have clients that would like to use it but because
prereqs is so restrictive, it doesn't work OOB for them. I
have two clients that tried but couldn't. (Two points does not
a data trend make.)
Robert: I heard from one more, does 3 make a trend?
Eliot: supplying a new constraint module would be the most
approproate action
Kris: I think the best we can do is provide an example topic
showing how to create such a constraint
Robert and Bob: [agreement that this is good enough]
Bob: We can't do more than that and be non-substantive
Kris: consensus: Update spec topics for task and general task
[ACTION] Robert to add this to the 1.3 errata page
Eliot: We could put something up on github
Kris: We do not have a generic OASIS github repository, we
have repositories for two specific topics projects
Robert: We would need to have a designated owner according to
OASIS procedures
Kris: Summary: action item for robert; also we should make a
non-normative example topic for creating this machinery task
body constraint that would match the strict task body
constraint
8. Continued item: OASIS Jira for DITA TC use?
----------------------------------------------
https://lists.oasis-open.org/archives/dita/201605/msg00038.html (Scott
Hudson, 24 May 2016)
Dick: An overview of JIRA review:
JIRA is an issue-tracker, also used (confused?) for project
management to some degree. Several OASIS TCs use it including
TOSCA and ODATA (can find pointers in Scott's email to the
list). It allows you to classify issues by the type of issue
(e.g. improvement, new feature, task of some kind; there is
some flexibility in issue type), to assign versions (e.g.
candidate release, major release) and to assign components
(e.g. DITA could be assigned to L&T, base, etc.). You can
create an issue, give it a status, give priority, give it an
owner, track it as it goes along. Groups use it for tracking
issues or requests for enhancements. E.g. out of this meeting
we could have assigned the XSD stuff that Eliot took as an
action; we could assign that as a task and track it that way.
Some actually put public review comments in there (this might
be overkill; hard to say). Some even talked about doing action
items but I didn't see any like ours; we could track ours but
not sure we'd want to. Can get an RSS feed. Can see it all
publicly but can't write to it unless logged in (maybe would
also need to be part of the TC).
It seems to be used primarily to track things like I just
mentioned. E.g. you have discussion and TC decides to do
something, it gets tracked in some status.
W.r.t. DITA it seems it could be useful possibly if we focused
on things that were done in Trello.
In email from Scott there was discussion about Agile; I'm
ignorant of Agile, so have no comment on its usefuleness for
Agile.
Stan: how much admin support would be available from OASIS? Do
TCs take the burden of administration for their repository?
Dick: It looked like they would be willing to help; OASIS have
been using JIRA since 2010 at least. Setup appears not too
difficult, boils down to selecting statuses you want (from a
preselected narrow set), deciding on components, versions etc.
Chet [Ensign] seems willing to help out. There may not be
"formal" support.
Kris: I concur about the level of support. There are limits to
what configuration can be done. OASIS provides a basic
configuration for TCs, not the general level of configuration
that you would have if setting up JIRA for your own company.
Kris: it comes down to whether it is more or less effort than
existing processes
Dick: We would not use it for easy issues like "read this and
report next week". We would use it for more weighty issues
needing tracking week to week. Especially ones that need
weekly comments.
Meeting adjourned 12:01pm ET, 9:01am PT.
-- Mr. Tom Magliery
|