RE: [dita] strict task vs. general task vs. the file naming and module rules

["Gershon Joseph (gerjosep)" <gerjosep@cisco.com>]

I also, still, vote for option 1. Let's do the right thing, and address the problem via education and documentation. The Adoption TC needs to develop an upgrade guide that is reviewed by this TC for technical accuracy.

 

--

Gershon

 

---

From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Friday, November 13, 2009 5:35 PM
To: JoAnn Hackos
Cc: dita; Park Seth-R01164
Subject: RE: [dita] strict task vs. general task vs. the file naming and module rules

JoAnn wrote: 

>Why did the TC not anticipate 
this problem when the decision was first made by the 
>“design group” to recreate task using constraints? 

Good question. I think when 
we use new features in our design work, there is a greater risk that we will 
miss consequences since we don't have experience with their use. We've recovered 
from some of these consequences through design changes (like the reuse across 
constrained models) but we should do better. 

>At best, this situation points to problems with our 
discussion and acceptance of proposals for 
>new features. 

I agree. I'd suggest adding a specific section to our proposal template 
that asks for "implications for existing specializations",  I think we 
failed to go into the technical due diligence on that question because it was 
never asked. 

>So – I’d 
opt for Option 2, has Jeff has so clearly explained it. 

I'd still opt for option 1. But I definitely understand 
the concerns. It's just a question of which is worse: 
- relaxing our naming model and having deprecated modules 
for the next five years or more, followed by a backwards-incompatible change 
- or taking the hit now, with as much 
education and explanation as possible to soften the blow for affected users 
today 

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

From:	"JoAnn Hackos" <joann.hackos@comtech-serv.com>
To:	"Park Seth-R01164" <R01164@freescale.com>, "dita" <dita@lists.oasis-open.org>
Date:	11/11/2009 02:18 PM
Subject:	RE: [dita] strict task vs. general task vs. the file naming and module rules

---

Since I originally brought up 
Option 3 to begin the discussion, I should point out that I fully understand the 
difficulties and awkwardness that Michael has summarized in having two equal 
task models. Seth’s points, however, are well stated. I am concerned with the 
apparent feeling of “bait and switch.” Why did the TC not anticipate this 
problem when the decision was first made by the “design group” to recreate task 
using constraints? 
  
At best, this 
situation points to problems with our discussion and acceptance of proposals for 
new features. I don’t recall the decisions about using constraints for task. I 
do recall the discussion of general task in which we thought a more general task 
model was appropriate. I have the same unease with the acceptance of the 
glossary proposal that usurped the work that the Translation SC had done on 
acronyms earlier. That proposal should have been sent to the SC first because it 
created a glossary structure that seems to be overkill and complicates the 
simpler acronym issue. 
  
In any event, I 
understand why we probably cannot decide on Option 3. I strongly believe that 
Option 1 is highly inappropriate and will cause untold problems for 
organizations who have been early and strong supporters of DITA. Many of us 
prefer the strict model because it keeps authors from creating all sorts of 
unusable procedures. Too bad if they didn’t know how to write in their earlier 
environments. Might as well use DITA to promote sound technical communication 
principles. 
  
So – I’d opt for Option 2, has Jeff 
has so clearly explained it. I cannot be on the call next week because of the 
DITA Europe conference so take my “vote” by proxy for Option 2. 
  
More importantly, however, we need to ensure that the issues with new 
proposals are clearly understood by everyone on the TC for the 1.3 discussions. 
Too often, the proposals are too obscure, the use cases missing, and the 
negative consequences unanticipated. Perhaps we need a new section in the 
proposals stating possible negative consequences of adoption. And – those of us 
who represent the non-XML geek community need to be certain we understand what 
the proposals are actually proposing. 
  
Thanks for all 
the attention to this issue. 
  
JoAnn 
  
JoAnn Hackos PhD 
President 
Comtech Services, Inc. 
joann.hackos@comtech-serv.com 
Skype joannhackos

---

From: Park Seth-R01164 [mailto:R01164@freescale.com] 
Sent: Wednesday, November 11, 2009 9:39 AM
To: 
dita
Subject: RE: [dita] strict task vs. general task vs. the file 
naming and module rules 
  
I request that option 3 remain on the table. The 
record should reflect that it was considered and supported by at least one 
member. I dont think there is any reason to discuss it further. I feel that my 
points (summarized below) have been understood, considered, and voted down 
fairly. 
  
1.        We should not re-invent the past. Re-creating task as a constraint of 
general task is a bait-and-switch approach that aims to atone for a structure 
type that is too constrained for many users. 
2.       
 The only proper way to create a new 
structure type is to specialize from an existing structure type that is less 
restrictive than the desired new structure type. Hence, the only proper way to 
create a general task (assuming you cannot re-invent the past) is to create it 
from topic. 
3.        Those who would use general task will likely have no content in the task 
model (if they did, then they probably dont need general task). Therefore, the 
desire for re-use between task and general task is not compelling enough to set 
a precedence for following the rules only when it's convenient. Along the same 
lines, there is not problem with reuse between task and general task, because 
there presently is no general task. Only when general task is unveiled will it 
become a problem to the users who wake up to one of the workarounds that we 
force users to deal with. 
4.       
 Creating general task from topic is simple, 
clean, and obeys all the rules and fundamental DITA principles. 
5.   
     Fall-back styling from topic 
is sufficient. 
6.        No workarounds required, unless you want to begin using the new general 
task model and share content. The archspec clearly defines 
generalization/specialization requirements. A simple transform can take an 
entire data set from the task model to the general task model. One time 
migration, zero time lost messing with constraint domains, catalogs, module 
names, loose/strict conref validation, etc. 
  
I still 
have no idea what benefit anybody gets by the proposed method of creating task 
from general task, but, I defer to the wisdom of the TC. 
  
Respectfully, 
-seth park

---

From: Ogden, Jeff [mailto:jogden@ptc.com] 
Sent: Tuesday, November 10, 2009 8:28 AM
To: 
dita
Subject: [dita] strict task vs. general task vs. the file naming 
and module rules 
Back to our continuing 
saga of strict task vs. general task vs. the file naming and module rules and 
compatability between DITA 1.0, 1.1, and 1.2 task customizations. 
  
I've 
been trying to think of ways to make progress on this issue. 
  
My collusion 
is that we are trying too hard to reach a consensus and in trying to do that 
we've put more and more compromises on the table, each one more complicated, 
more confusing, and less satisfactory. I think we should stop doing that, put 
the fundamental alternatives on the table for the TC to discuss once more and 
then have the TC vote to choose one of the alternatives. 
  
My suggestion 
is that the TC choose between these two alternatives: 
  
1.  Status 
quo. Users with customized DITA 1.0 or 1.1 task document type shells will 
implicitly switch from the strict to the general task model when they move to 
DITA 1.2 unless they take steps to add the new strict task constraint to their 
existing specializations. We continue to follow all of the design pattern rules 
for file naming and module separation. This is option #1 in the summary table 
below. 
  
2. 
 Make changes so that existing 
DITA 1.0 and 1.1 task customizations remain compatible in DITA 1.2. Add new 
files and make changes to existing files, PUBLIC IDs, and URIs so that existing 
DITA 1.0 and 1.1 task document type shells continue to use the strict rather 
than the general task model. This will violate the existing design pattern file 
naming and module separation rules. In the DITA 1.2 spec. make the file naming 
rule a SHOULD rather than a MUST. Place the files (task.mod and taskMod.xsd) 
that violate the module separation rules in a deprecated directory where they 
will not be used by any other DITA 1.2. We will keep the deprecated directory 
and non-conforming files until we get to DITA 2.0 where we can make incompatible 
changes. 
  
Either approach will require updates to the DITA 1.2 spec. 
to explain to people what is going on and what they need to do to get various 
behaviors that they may want. 
  
No matter which option the 
TC chooses we should add new PUBLIC IDs and URIs that include the phrases 
“strict task” and “general task” rather than simply “task” so that it is clearer 
what type of task model one is getting when using the various doctype shells and 
modules. We would maintain the existing unqualified “task” PUBLIC IDs and URIs 
to maintain compatibility with prior releases. 
  
Not included is a third 
alternative that the TC has previously decided not to pursue: 
  
3.  Abandon constraints as the method to create general and strict 
tasks in favor of a new specialization and new doctype shells that avoid the 
problems associated with reusing the existing task.mod and taskMod.xsd files and 
identifiers for new purposes. 
  
If someone on the TC feels 
strongly that this alternative should be considered, they should say so. 
  
As 
I’m sure everyone knows by now, I prefer option #2.  I don’t like option 
#1, but I do think it is better than alternative #3. 
  
Here is a 
summary that was put together during some private e-mail exchanges between 
Michael, Robert, and me and then updated by me to reflect the details of the 
current proposals. 
  
|------------------------+------------------------+------------------------| 
|Option             
     |Who benefits?           |Who's 
hurt, and when?   | 
|------------------------+------------------------+------------------------| 
|1. Do nothing.         
 |1) No new DTD / Schema  |1) People with         
 | 
|         
               |   updates required 
    |customized shells that  | 
|                     
   |                   
     |do not want the loose   | 
|                 
       |2) People who want the  |task model, and who 
have| 
|           
             |   loose model   
       |not read the spec to    | 
|                 
       |   automatically       
 |find out about the      | 
|                     
   |                   
     |change. Affected as soon| 
|                     
   |                   
     |as they move to 1.2. If | 
|                     
   |                   
     |they notice quickly,    | 
|                 
       |               
         |they can learn how to   | 
|             
           |           
             |add the constraint and 
 | 
|         
               |       
                 |add it; if they 
notice  | 
|       
                 |     
                   |late, they 
may already  | 
|       
                 |     
                   |have docs 
that make it  | 
|     
                   |   
                    
 |tough to add the        | 
|                 
       |               
         |constraint.         
    | 
|------------------------+------------------------+------------------------| 
|2. Rename the existing  |1) People with 
custom   |1) People who do not use| 
|task.mod to be          |shells who want the 
    |catalogs for their local| 
|generalTask.mod, create |strict model. I am     
 |doctypes - but they're  | 
|new 
PUBLIC IDs and URIs |assuming the deprecated |already in trouble due 
 | 
|that point to the “new” |task.mod 
gives the      |to our new directories, | 
|file, change all of the |strict model in one way |so 
they'll just be a bit| 
|DITA 1.2 files 
that we  |or another.             | more 
confused that task| 
|distribute to use the 
  |                     
   | is now "deprecated"    | 
|new PUBLIC IDs or URIs, |             
           |           
             | 
|rename the task doctype |             
           |2) People who rely on   | 
|shells to strictTask.dtd|       
                 |catalogs for the 
DTD    | 
|or .xsd, keep the 
      |                 
       |doctypes - but they're  | 
|existing PUBLIC ID and  |         
               |only, but system IDs 
for| 
|URIs for the task     
  |                     
   |the modules, are also   | 
|doctype shells pointing |             
           |forced to change       
 | 
|to strictTask, create   | 
                      
 |more confused that task | 
|new 
“strictTask” PUBLIC |                 
       |is now "deprecated"     | 
|IDs and URIs that also  |         
               |2) People who rely on 
  | 
|point to the strictTask |   
                    
 |catalogs for the DTD    | 
|doctype shells, create  |             
           |only, but system IDs for| 
|deprecated/dtd/task.mod |       
                 |the modules, are 
also   | 
|and       
              |         
               |forced to change   
     | 
|deprecated/xsd/taskMod.x|             
           |           
             | 
|sd and point the        |       
                 |     
                   | 
|existing PUBLIC IDs and |       
                 |     
                   | 
|URIs at it.           
  |                     
   |                   
     | 
  
  
   -Jeff