RE: [dita] RE: Updated summary: task vs. general task, constraints, conref, andother related issues

[Michael Priestley <mpriestl@ca.ibm.com>]

There is a potentially much larger fourth
group of people who would create custom doctypes if they had a tool that
could automate it. While such a tool could be programmed to allow for exceptions
that we name in the spec, it sure would be nice if it worked consistently
with the same rules for any specialization, and didn't require exceptions
to handle our own special case. If we introduce exceptions, how can we
expect others not to?

I think the confusion we saw on this
list resulted from a collision between group 1 (out of the box focused
users) and group 2 (DTD experts). Hopefully we resolved those issues, precisely
so that they don't cause a problem for those groups in the outside world.
I don't think that any of the confusion on the TC came from group 3 users.

But basically I agree that there is
a problem here: people migrating a custom task shell from 1.1 to 1.2 can
get unwanted results. I just disagree with the cure. I think the impact
of breaking our naming conventions is potentially going to be felt by all
future specializers who look to our stuff for examples. 

I'm struggling to come up with some
alternatives. Maybe a migration utility? Maybe a specialization validator
that posts an info message to users with custom task doctypes if they don't
have the constraint? At the very least an article or tutorial, dealing
specifically with the migration of a custom task doctype.

I realize these are all bandaids. They're
things a user would need to run or read to know what they need to do, and
if they don't they could end up producing a loose task model, which if
they roll out to users without testing would allow the creation of looser
tasks than they intended.

But on the other hand, if we break our
own naming conventions, people will inevitably copy the breakage. And anything
we do to correct that behavior will also be in the form of bandaids: validation
services, articles, etc. Either way we will be creating a problem, and
either way the best answer will miss some groups.

For me, the issue of module naming conventions
is strategic: they provide the potential for easy interchange of content
and doctypes, even for auto-assembly of doctypes based on normalized document
samples. And the issue of general task vs constrained task is tactical:
it will only matter for this release, for a subset of users, and I think
we should target those users with help, guidance, and tools to the best
of our ability.

Michael Priestley, Senior Technical
Staff Member (STSM)
Lead IBM DITA Architect 
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

From:	"Ogden, Jeff" <jogden@ptc.com>
To:	"ekimber" <ekimber@reallysi.com>, "dita" <dita@lists.oasis-open.org>
Date:	10/19/2009 10:06 PM
Subject:	RE: [dita] RE: Updated summary: task vs. general task, constraints, conref, and other related issues

---

It seems to me that organizations that
use DITA fall into one of three broad categories:
 
1.  Organizations that only use DITA
"out of the box", where the "box" may be from OASIS
or it may be from a vendor. These organizations don't have their own specializations
and have little to worry about in terms of the strict vs. general task
questions as long as their "box providers" do a good job.
 
2.  Organizations that have information
architects, know the ins and outs of DTD and XSD programming, and should
generally be able to look after themselves as far as the strict vs. general
task questions go, particularly if the DITA specification and/or some best
practice documents alert them what to watch out for.
 
3.  Organizations that fall between
the other two groups. These organizations may be using specializations
that they developed themselves, that were developed for them by consultants,
or that they received from third parties that may or may not be providing
on-going support.  They may have some in house expertise, but they
may be struggling to keep up with everything they need to do.  Or
the in-house experts may have left to work on another project or have left
the organization all together. The consultants that they hired may or may
not still be working for them.  The organizations may not upgrade
to DITA 1.2 on their own schedule, but the upgrade may happen as a side
effect of upgrades to their tools provided by a tool vendor.
 
It is this third group that I am concerned
about as we talk about allowing an implicit change from strict task to
general task for people who are using task.mod in private specializations
and who upgrade to DITA 1.2 without updating their specializations to include
the strict task constraint.
 
And since many of the folks on the DITA
TC got caught by this themselves, I wonder how many organizations are really
in the second group and can be expected to truly look after themselves.
 
   -Jeff  
 
> -----Original Message-----
> From: ekimber [mailto:ekimber@reallysi.com]
> Sent: Monday, October 19, 2009 12:21
PM
> To: Ogden, Jeff; dita
> Subject: Re: [dita] RE: Updated summary:
task vs. general task,
> constraints, conref, and other related
issues
> 
> I cannot agree to any solution that
does not result in the module for
> <task>
> being named task.mod.
> 
> That said, the *shells* can have
any name whatsoever.
> 
> Note that module names are of interest
only to those doing
> configuration and
> specialization. I think we have to
assume that anyone performing those
> tasks
> will already be required to at least
review the new DITA 1.2 concepts
> and
> rules and thus will have to understand
that there are these things
> called
> constraint modules, that they can
be applied via shells, and that the
> strict
> task shell (whatever we call it),
uses a constraint to emulate the DITA
> 1.1
> task model.
> 
> For users simply selecting a shell
DTD, either knowingly or indirectly
> through options provided by their
DITA-supporting tools, the only thing
> that
> will matter is the name of the shell
DTD. So the right answer would
> seem to
> be to choose shell names that will
be the best match/least surprising
> for
> both current 1.1 users and new 1.2
users.
> 
> That suggests to me that having task.dtd
reflect the constrained task
> is the
> least surprising.
> 
> On the other hand, having new names
like strictTask.dtd and
> generalTask.dtd,
> with *no* task.dtd shell provided
at all, would at least make it clear
> that
> there is a distinction and a break
(albeit a backward compatible one),
> with
> DITA 1.1.
> 
> I think it's also the case that there
*must* be a 1.1-to-1.2 migration
> guide
> for Information Architects that explains
this issue and a few others
> we've
> introduced (rename of glossary.*
to glossentry.*, final form of the L&T
> hierarchies). This guide could be
an informative appendix to the main
> spec,
> I should think.
> 
> Cheers,
> 
> Eliot
> 
> 
> On 10/19/09 11:06 AM, "Ogden,
Jeff" <jogden@ptc.com> wrote:
> 
> > During last weekıs DITA TC meeting
we resolved the first two open
> items on the
> > list of open questions related
to task vs. general task, constraints,
> conref
> > and other related issues.
> >
> >
> >
> > And we almost resolved the 3rd
and 4th items as well, but at the last
> minute
> > Michael and Eliot realized that
implementing the proposals for these
> two items
> > would mean that we wouldnıt
be following some aspects of our design
> > guidelines. Time ran out at
that point and so weıll be coming back to
> these
> > issues during our next meeting.
> >
> >
> >
> > The two remaining items are:
> >
> >
> >
> > 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 us 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.
> >
> >
> >
> > Don was working to combine the
two items into a single item as
> follows:
> > ³changing filenames for compatibility
and clarity². But at least for
> item #4
> > there is a little more to it
than just changing filenames.
> >
> >
> >
> > Since it seems likely that there
is going to be substantial
> opposition to
> > these two items, after last
weekıs call I tried to figure out if it
> was worth
> > it to continue to push for these
two items.  My conclusion is that
> the changes
> > are worth making even if we
donıt follow all of our own design
> guidelines.  My
> > thinking is that the changes
will avoid a change in behavior for
> existing
> > specializations that use task.mod
(from strict to general task), as
> well as
> > reduce the chance for confusion
going forward, that weıve already
> seen
> > confusion caused by this on
the part of the DITA TC, and we really
> need to try
> > and make things easier and more
understandable for folks with less in
> depth
> > knowledge of DITA, DTDs, and
XSDs.  And we can mitigate the issues of
> not
> > strictly following the design
guidelines by providing and using good
> examples
> > as alternates to the files that
do follow the guidelines. In the
> files and in
> > the Architecture Spec. we 
can include an explanation of what we are
> doing,
> > why we are doing it, and stating
that the files that do not follow
> the
> > guidelines should not be used
as examples for the future development.
> >
> >
> >
> > So my current suggestion is:
> >
> > ·        
That we not combine items 3 and 4.
> >
> > ·        
That we split item 3 into two parts:
> >
> > 3a) changing names that do follow
the design guidelines (task.dtd
> becomes
> > strictTask.dtd, with task.dtd
kept for compatibility, but deprecated);
> and
> >
> > 3b) changing names in ways that
do not follow the design guidelines
> (task.mod
> > becomes generalTask.mod, with
task.mod kept for compatibility, but
> > deprecated).
> >
> > ·        
And that the TC consider items 3a, 3b, and 4 separately.
> >
> >
> >
> > The objection to item 3b is
that the name of the file
> (generalTask.mod wonıt
> > match the name of the information
type or top tag, task).
> >
> >
> >
> > The objection to item 4 is that
adding the Strict Task Constraint to
> task.mod
> > violates the principle that
integration of types, domains, and
> constraints is
> > done in document type shells
and not in modules.
> >
> >
> >
> >    -Jeff
> >
> >
> >
> >
> >
> > From: Ogden, Jeff
> > Sent: Sunday, October 11, 2009
4:07 PM
> > To: 'dita'
> > Subject: Updated summary: task
vs. general task, constraints, conref,
> and
> > other related issues
> >
> >
> >
> > 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
> > <http://wiki.oasis-
> open.org/dita/Summary%20of%20task%20vs.%20general%20task,%2
> > 0constraints,%20conref,%20and%20other%20related%20issues> 
under the
> ³Working
> > Documents, DITA 1.2² section
of the DITA TC Wiki page
> > <http://wiki.oasis-open.org/dita/FrontPage>
.
> >
> >
> >
> > 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:
> >
> >
> >
> > 5.    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
> > <http://www.oasis-
> open.org/apps/org/workgroup/dita/email/archives/200910/msg00
> > 051.html>  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..
> >
> >
> >
> > 6.    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.
> >
> >
> >
> > 7.    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.
> >
> >
> >
> > 8.    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:
> >
> >
> >
> > 9.    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.
> >
> >
> >
> > 10.  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.
> >
> >
> >
> > 11.  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.
> >
> >
> >
> > 12.  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.
> >
> >
> >
> > 13.  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.
> >
> >
> >
> > 14.  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.
> >
> >
> >
> > 15.  Eliot added some questions
about topic nesting, conref
> validation, and
> > the domains attribute to the
list of things to consider for DITA 1.3.
> >
> 
> ----
> Eliot Kimber | Senior Solutions Architect
| Really Strategies, Inc.
> email:  ekimber@reallysi.com
<mailto:ekimber@reallysi.com>
> office: 610.631.6770 | cell: 512.554.9368
> 2570 Boulevard of the Generals |
Suite 213 | Audubon, PA 19403
> www.reallysi.com
<http://www.reallysi.com> 
| http://blog.reallysi.com
> <http://blog.reallysi.com>
| www.rsuitecms.com
> <http://www.rsuitecms.com>