OASIS Darwin Information Typing Architecture (DITA) TC

The ongoing discussion that started with Joann’s notes
about “Problems with the task model” has become quite wide
ranging.  So wide ranging, that I’m having trouble keeping track of
what we have decided for DITA 1.2, what remains to be decided for DITA 1.2, and
what are a topics for future discussion for DITA 1.3 or DITA 2.0.  This
note is my attempt to summarize the discussion so far.



1.      
The TC has decided that strict task rather than general
task should be included in the ditabase doctype shell that is included as part
of Technical Content. DTDs, XSDs, and the DITA 1.2 specification will all need
to be updated.



2.      
There is an open question about the need to include a second
ditabase doctype shell that would include general task rather than strict task. 
The TC seemed to be leaning toward not including a second ditabase doctype
shell, but I don’t think there is a consensus about that and a final
decision remains to be made.  If a decision is made to include a second
ditabase, we would need to pick a location for the additional doctype shell, filenames,
a Public ID, and a URI, and the DTDs, XSDs, and the DITA specification would
all need to e updated.



3.      
There is a preliminary proposal to allow “weak”
constraints to be declared. So far no one has raised technical complaints about
the proposal. There has been support for including the proposal as part of DITA
1.2 expressed by several people. There have been reservations about considering
the proposal this late in the DITA 1.2 cycle. I expressed a reservation about this
making things more complicated with the possibility of yet more combinations of
things.  There is a concern that MP and others may not have the necessary
bandwidth in the short run to turn this into a more formal and complete
proposal. If the proposal does go forward, the TC will need to make some
decisions about using “week” or “strict” constraints
for task.dtd and ditabase.dtd.



4.      
There have been a lot of discussions about what is and
isn’t or what should and shouldn’t be valid when using conref. There
is one question about doing conref validation based on content models in DTDs
or XSDs rather than information in the domains attribute value.  I’m
not aware of any other specific open questions or decisions for DITA 1.2 coming
out of this portion of the discussion.



5.      
Questions have been raised about the constraints mechanism
in general and if it was appropriate to use it to implement the new versions of
task that are part of DITA 1.2.  I don’t think there has been a
formal proposal to withdraw constraints from DITA 1.2 or to reimplement the
versions of task without using constraints, but that might yet come up.



And that is pretty much everything that I think has come up
in the public discussions so far.  Did I leave anything out?



I’ve been involved in or started some private
discussions where some other issues were raised:



6.      
The names we have for task.dtd, generalTask.dtd,
task.mod, task.ent, strictTaskbodyConstraint.mod and the associated XSDs,
Public IDs, and URIs seem confusing.  Would new names for some of the
these items help?  For compatibility reasons we’d probably need to
use the same sort of trick we used with glossary and glossentry, so the old
names would continue to work.



7.      
Are many of the issues we’ve been discussing tied
to shortcomings of ditabases and shortcomings of DTDs --that a ditabase can
only contain a single use (constrained or unconstrained) of a particular info type? 
Should we look for a way to remove or relax that restriction in DITA 1.3 or
2.0?



8.      
Some questions about topic nesting, conref validation,
and the domains attribute that Eliot added to the list of things to consider
for DITA 1.3.



I’m guessing that there may be other topics from private
discussions that aren’t known to the entire list. If there are and if
they need to be considered for DITA 1.2, please put them forward now.



   -Jeff

Hi Jeff,

Thanks for the write up.

I've also had trouble following some of the issues. I thought that at least
some of the problems came from mixing up the issues of 1) how do
constraints work in general, and 2) how do we deal with our task
distribution in particular. I put together an FAQ on constraints today
before I saw your note, hoping that it might address some of the confusion
about the general item. It's quite possible that I've left off some
questions that have come up; I'd suggest that any other questions should be
added, but that answers should be kept as short and simple as possible.
http://wiki.oasis-open.org/dita/ConstraintsFaq

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit


                                                                           
             "Ogden, Jeff"                                                 
             

Here is
the updated summary of the issues related to task vs. general task,
constraints, conref, and other related issues that I agreed to send following
today's DITA TC meeting.  It is just a reordered and updated version of the
message I sent before the DITA TC meeting.



Robert
wrote an FAQ about constraints that everyone who is interested in this topic
should read:



            http://wiki.oasis-open.org/dita/ConstraintsFaq




Here are
the open questions. Only items 1, 2, 3, and 4 were discussed during today’s TC
call. Item 4 was only discussed very briefly.



1.    Questions have been raised about the
constraints mechanism in general and if it was appropriate to use it to
implement the new versions of task that are part of DITA 1.2.  At the TC
meeting Joann made a proposal to abandon the current approach of using
constraints to implement general and strict task in DITA 1.2.  As an
alternative she suggested two peer task specializations both based on topic. Others
suggested that implementing strict task as a specialization of general task without
using constraints as another approach.  After a good deal of discussion, it was
decided that we should stick with the current approach of using constraints to
implement strict task based upon general task.



2.    It has been stated that within a
single organization or within a single authoring group, that in general only
one version of an information type SHOULD be used within a group and that we
should explain why that is the case and recommend that approach somewhere in
the DITA 1.2 specification as well as in a best practices document that might
be written by the DITA Adoption TC.  There were a number of questions about
exactly what should be said and where it should be said, but there seems to be
agreement that something should be said somewhere.



3.    There was a question about the wisdom
of including both task.dtd (strict task) and generalTask.dtd in the DITA 1.2
specification. No final decision was made, but the TC seemed to be leaning in
the direction of including both with appropriate warnings and recommendations in
the specification and a best practice.



4.    There is a preliminary proposal to
allow “weak” constraints to be declared. So far no one has raised technical
complaints about the proposal. There has been support for including the
proposal as part of DITA 1.2 expressed by several people. There have been
reservations about considering the proposal this late in the DITA 1.2 cycle. I
expressed a reservation about this making things more complicated with the
possibility of yet more combinations of things.  There is a concern that
MP and others may not have the necessary bandwidth in the short run to turn
this into a more formal and complete proposal. MP said he would think about his
time over the coming week, but that he didn’t think this would be a huge effort
and that he could probably accommodate it.  Others stated that there were
constraints on their own time (they didn’t say if those constraints were strong
or weak). If the weak constraints proposal does go forward, the TC will need to
make some decisions about using “week” or “strict” constraints for task.dtd and
ditabase.dtd



5.    An alternative that was not discussed
would be to make all constraints “weak” as far as conref validation is
concerned in DITA 1.2 without the need to declare them as such.  Given the
current state of many conref validation implementations, this is pretty much
the de facto state of affairs today.  If “weak” constraints were the norm for
DITA 1.2, “strong” constraints could be added in DITA 1.3 using s(…).



6.    There have been a lot of discussions
about what is and isn’t or what should and shouldn’t be valid when using
conref. There is one question about doing conref validation based on content
models in DTDs or XSDs rather than information in the domains attribute
value.  Several people pointed out why DITA doesn’t use the actual content
models in the DTDs or XSDs for conref validation and instead uses values from
the domains attribute. I’m not sure there is still an open question related to
this. I’m not aware of any other specific open questions or decisions for DITA
1.2 coming out of this portion of the discussion.



7.    The TC has decided that strict task
rather than general task should be included in the ditabase doctype shell that
is included as part of Technical Content. DTDs, XSDs, and the DITA 1.2
specification will all need to be updated.



8.    There is an open question about the
need to include a second ditabase doctype shell that would include general task
rather than strict task.  The TC seemed to be leaning toward not including
a second ditabase doctype shell, but I don’t think there is a consensus about
that and a final decision remains to be made.  If a decision is made to
include a second ditabase, we would need to pick a location for the additional
doctype shell, filenames, a Public ID, and a URI, and the DTDs, XSDs, and the
DITA specification would all need to e updated.



9.    The names we have for task.dtd,
generalTask.dtd, task.mod, task.ent, strictTaskbodyConstraint.mod and the
associated XSDs, Public IDs, and URIs seem confusing.  Would new names for
some of the these items help?  task.dtd might become strictTask.dtd,
task.mod à genTask.mod, task.ent à
gentask.ent. For compatibility with DITA 1.1 and 1.0 we’d probably need to use
the same sort of trick we used with glossary and glossentry, so the old names
would continue to work.



10.  Many of the issues we’ve been
discussing seem to arise from shortcomings of ditabases and shortcomings of
DTDs --that a ditabase can only contain a single use (constrained or
unconstrained) of a particular info type.  Should we look for ways to
remove or relax that restriction in DITA 1.3 or 2.0?



11.  Eliot added some questions about topic
nesting, conref validation, and the domains attribute to the list of things to
consider for DITA 1.3.



If I’ve
left anything out or there are other questions that need to be discussed and decided,
please add them to the list.



    -Jeff

Here is another
updated summary of the issues related to task vs. general task, constraints,
conref, and other related matters.



The
summary is also available as a Wiki
page under the “Working Documents, DITA 1.2” section of the DITA TC Wiki page.



I’ve
placed the issues into two groups.  The first group includes questions that
still need to be resolved.  The second group includes issues that I believe have
been resolved or deferred.



If I’ve
left anything out or there are other questions that need to be discussed and
decided, please add them to the list.



Robert
wrote an FAQ about constraints that everyone who is interested in this topic
should read:



           
http://wiki.oasis-open.org/dita/ConstraintsFaq




Open
questions:



1.    There was a preliminary proposal to
allow “weak” constraints to be declared. Michael formalized this as a
proposal to allow both “strong” and “weak” constraints validation with “weak”
being the default. No one raised technical complaints about the original proposal.
There has been support for including the proposal as part of DITA 1.2 expressed
by several people. There have been reservations about considering the proposal
this late in the DITA 1.2 cycle. If the strong/weak constraints proposal goes
forward, my assumption is that we will use the default of “weak” in task.dtd
and in ditabase.dtd.  The proposal requires changes to the written specification,
but no changes to the DTDs or XSDs. It may require changes to some implementations,
but perhaps not difficult or extensive changes.



Proposal: Accept Michael’s proposal for DITA
1.2 with “weak” conref validation of constraints as the default and “strong”
conref validation of constraints something that may be implemented, but is not
required..



2.    There is an open question about the
need to include a second ditabase doctype shell that would include general task
rather than strict task.  The TC seemed to be leaning toward not including
a second ditabase doctype shell, but I don’t think there is a consensus about
that and a final decision remains to be made.  If a decision is made to
include a second ditabase, we would need to pick a location for the additional
doctype shell, filenames, a Public ID, and a URI, and the DTDs, XSDs, and the
DITA specification would all need to be updated.



Proposal: Include only a single ditabase
document type in DITA 1.2.



3.    The names we have for task.dtd,
generalTask.dtd, task.mod, task.ent, strictTaskbodyConstraint.mod and the
associated XSDs, Public IDs, and URIs seem confusing.  Would new names for
some of the these items help?  task.dtd might become strictTask.dtd,
task.mod --> genTask.mod, task.ent --> gentask.ent. For compatibility
with DITA 1.1 and 1.0 we’d probably need to use the same sort of trick we used
with glossary and glossentry, so the old names would continue to work.



Proposal:  To make some name changes so that
it is clearer what each file includes or does.



4.    Any user specializations based on
task.mod from DITA 1.0 or 1.1 will switch from being strict to general task
based specialization when people move to DITA 1.2 unless explicit action is
taken to add the strict task constraint to the specialization.  This is pretty
much want happened to use with ditabase.dtd. We need to add something to the
DITA 1.2 specification warning people about this possibility. Or, if we rename
some items as suggested in the previous item, we might be able to avoid this
problem by having a genTask.mod, a strictTask.mod, and a task.mod where
task.mod would include the strict task constraint.



Proposal: To make a change along the lines of
the later suggestion, so that previously existing specializations based on task.mod
include the strict task constraint and so do not implicitly change when used with
DITA 1.2.



Issues
that I believe have been resolved or which have been deferred to DITA 1.3 or
2.0:



5.    The TC has decided that strict task
rather than general task should be included in the ditabase doctype shell that
is included as part of Technical Content. DTDs, XSDs, and the DITA 1.2
specification will all need to be updated.



6.    Questions were raised about the
constraints mechanism in general and if it was appropriate to use it to
implement the new versions of task that are part of DITA 1.2.  At the TC
meeting two weeks ago Joann made a proposal to abandon the current approach of
using constraints to implement general and strict task in DITA 1.2.  As an
alternative she suggested two peer task specializations both based on topic.
Others suggested that implementing strict task as a specialization of general
task without using constraints as another approach.  After a good deal of
discussion, it was decided that we should stick with the current approach of
using constraints to implement strict task based upon general task.



7.    It has been stated that within a
single organization or within a single authoring group, that in general only
one version of an information type SHOULD be used within a group and that we
should explain why that is the case and recommend that approach somewhere in
the DITA 1.2 specification as well as in a best practices document that might
be written by the DITA Adoption TC.  There were a number of questions
about exactly what should be said and where it should be said, but there was
agreement that something should be said in both the DITA specification and in a
best practices document.



8.    There was a question about the wisdom
of including both task.dtd (strict task) and generalTask.dtd in the DITA 1.2. Given
the previous item we will include both with appropriate warnings and
recommendations in the specification and a best practice.



9.    There was a lot of discussion about
what is and isn’t or what should and shouldn’t be valid when using conref.
There was one question about doing conref validation based on content models in
DTDs or XSDs rather than information in the domains attribute value. 
Several people pointed out why DITA doesn’t use the actual content models in
the DTDs or XSDs for conref validation and instead uses values from the domains
attribute. 



10.  Many of the issues we’ve been
discussing seem to arise from shortcomings of ditabases and shortcomings of
DTDs --that a ditabase can only contain a single use (constrained or
unconstrained) of a particular info type.  We should look for ways to
remove or relax these restrictions in DITA 1.3 or 2.0.



11.  Eliot added some questions about topic
nesting, conref validation, and the domains attribute to the list of things to
consider for DITA 1.3.