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:]

> 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"
<> 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:  
<mailto:>

> 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>