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

[ekimber <ekimber@reallysi.com>]

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>