OASIS Darwin Information Typing Architecture (DITA) TC

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

This seems to have got 
garbled:
 
2) People who rely 
on  
catalogs for the DTD   
doctypes - but 
they're 
only, but system IDs for
the modules, are also  
forced to change       
more confused 
that task
is now "deprecated"

Could you sort it out, 
please?



  

  

  From: Ogden, Jeff [mailto:jogden@ptc.com]
Sent: Tuesday, November 10, 2009 9: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
  

Hopefully this is less garbled.



|------------------------+------------------------+------------------------|

|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      
|                       
|only, but system IDs for|

|existing PUBLIC ID and 
|                     
  |the modules, are also   |

|URIs for the
task      
|                       
| forced to change       |

|doctype shells pointing
|                       
|                       
|

|to strictTask,
create  
|                       
|                       
|

|new “strictTask”
PUBLIC
|                       
|                       
|

|IDs and URIs that also 
|                       
|                       
|

|point to the strictTask
|                       
|                       
|

|doctype shells, create 
|                       
|                       
|

|deprecated/dtd/task.mod
|                       
|                       
|

|and                    
|                       
|                       
|

|deprecated/xsd/taskMod.x|                   
    |                       
|

|sd and point
the       
|                       
|                       
|

|existing PUBLIC IDs and
|                       
|                       
|

|URIs at
it.            
|                       
|                       
|

|------------------------+------------------------+------------------------|











From: Bruce Nevin
(bnevin) [mailto:bnevin@cisco.com]

Sent: Tuesday, November 10, 2009 10:37 AM

To: Ogden, Jeff; dita

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







This seems to have got garbled:

 

2) People who rely on  

catalogs for the DTD   

doctypes - but they're 

only, but system IDs for

the modules, are also  

forced to change       

more confused that task

is now "deprecated" 

Could you sort it out, please?











From: Ogden, Jeff [mailto:jogden@ptc.com]

Sent: Tuesday, November 10, 2009 9: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

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.
 

  
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. 
  
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. 
  
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. 
  
Creating general 
  task from topic is simple, clean, and obeys all the rules and fundamental DITA 
  principles. 
  
Fall-back styling 
  from topic is sufficient. 
  
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

First, some background for others: there
were two proposals for a specialized solution. One inserted a new ancestor
type between topic and task. The other was Seth's proposal for a peer of
task; both task and general-task would derive from topic.

Seth wrote:
>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.

Seth, to remind you of some benefits
of constraints:

- we don't need to create new "general-task"
equivalents for every task element (about 20 new and entirely redundant
elements)
- we don't force future specializers
to select from two nearly-identical models for a specialization base 
- we don't create two parallel and redundant
processing branches for task elements, which will proliferate further with
more specializations
- we don't prevent reuse between the
two task models (in your model, we could not conref a step/general-step
in either direction)

Michael Priestley, Senior Technical
Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25





From:
"Park Seth-R01164" <R01164@freescale.com>

To:
"dita" <dita@lists.oasis-open.org>

Date:
11/11/2009 11:47 AM

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
 

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
 

On 11/13/09 12:04 PM, "Bruce Nevin (bnevin)" 

On 11/13/09 2:20 PM, "Joann Hackos" 

So you're saying that *no* *one* is affected by this change unless they use local shells for 

On 11/13/09 3:00 PM, "Bruce Nevin (bnevin)" 

Eliot wrote:

> I don't think it's going to come as a surprise to
any 1.1 user that 1.2 is a significant change to DITA.



It might if we continue to
claim that DITA 1.2 is compatible with DITA 1.1.  



I still hope we do not go
forward with option (1), but if we do, I don't think we can continue to claim
that DITA 1.2 is compatible with DITA 1.1 and 1.0. Instead I think we'll need
to say something like:  



·        
DITA 1.2 is mostly compatible
with DITA 1.1 and 1.0.

·        
DITA 1.2 is largely
compatible with DITA 1.1 and 1.0.

·        
DITA 1.2 is
compatible with DITA 1.1 and 1.0 except for the following changes xxxx, xxxx, ...,
and xxxx.

·        
DITA 1.2 is
compatible with DITA 1.1 and 1.0 except for the items listed in Appendix XX of
the DITA 1.2 Architectural Specification.



Is anyone working on a draft
of the “upgrade guide” chapter or document that we’ve said is
needed?



Eliot also wrote:

> Note that the issue with the current release of
Arbortext Editor 5.4 is

> *not* the result of this design change, it is the
result of a mistake made

> by the Arbortext Editor development team.



It is true that the Arbortext
development team (that would be me) made a mistake here, but it is also true
that the TC distributed a draft version of the ditabase doctype shell that
contained a similar mistake.  And if we can make this sort of mistake, then
others will too. The TC’s mistake will be corrected soon (or quite likely
has already been corrected in the DTDs and XSDs that were posted earlier in the
week).



And Eliot also wrote:

> So I think we can assume that the current

> Arbortext Issue will be resolved before or very soon
after DITA 1.2

> reaches the final stages of approval.



I certainly hope so, but if
the TC doesn't make a decision soon we will miss an opportunity to fix this
issue in the next maintenance (minor) release for Arbortext Editor.  We’ve
got about three weeks to go. I guess I can go ahead and make a fix of my own
design if the TC doesn’t make a decision in time, but my solution is
likely to be option (2) and that may or may not be the solution that the TC
ultimately chooses.



I'm thinking of starting a
betting pool about if DITA 1.2 will be an officially approved OASIS standard
before the next major release of Arbortext Editor comes out. The TC and OASIS have
roughly 11 months to get this done to win that race. At this point it is not
clear which side of this bet I’ll take myself.



    -Jeff





> -----Original Message-----

> From: Eliot Kimber [mailto:ekimber@reallysi.com]

> Sent: Friday, November 13, 2009 3:42 PM

> To: Joann Hackos; Michael Priestley

> Cc: dita; Park Seth-R01164

> Subject: Re: [dita] strict task vs. general task vs.
the file naming

> and module rules

> 

> On 11/13/09 2:20 PM, "Joann Hackos"
<joann.hackos@comtech-serv.com>

> wrote:

> 

> > HI--

> >

> > I'm really opposed to this option (1). There is
absolutely no way we can

> > possibly inform everyone using DITA today that
they¹re in for big problems.

> > Are all of the vendors of all the editors
willing to place warnings on their

> > releases, which should have happened with
Arbortext 5.4? How will we

> > communicate the problem? Most users don¹t even
know of the existence of

> > dita.xml.org or any of the documentation from
either TCs.

> 

> To recap, this change affects the following users:

> 

> - Users using topics that are specialized from task
and that *did not*

> define new content models for taskbody. That seems
like a very small

> potential set, since most reasons to specialize from
task would be to

> further refine the details of the task body (e.g.,
specialized prerequisite

> markup, etc.), which means your specialization
already reflects the 1.1

> strict model and that won't change with a move to
1.2. Any group this

> sophisticated can probably handle the migration
without difficulty and

> has, in fact, probably been waiting eagerly to be
able to have a more

> flexible topic model to specialize from.

> 

> - Users using local shells for the base task topic
type. These users will

> see unconstrained content for topicbody until their
shells are updated to

> integrate the TC-provided constraint module. The
update task is easy to

> do--just copy the relevant lines from TC-provided
task.dtd into your task.dtd.

> 

> This group is probably a *bit* larger, but if my
so-far-quixotic attempts to

> get the community at large to understand the need
for local shells is any

> indication, there aren't too many groups using local
shells. Certainly

> very few users of Arbortext, XMetal, or FrameMaker
are.

> 

> Note that the issue with the current release of
Arbortext Editor 5.4 is

> *not* the result of this design change, it is the
result of a mistake made

> by the Arbortext Editor development team. That
mistake can easily be fixed

> by using a fix to 5.4, something PTC will have to do
when 1.2 is

> sufficiently stable in any case, in order to reflect
other late changes

> we've made to the markup design. So I think we can
assume that the current

> Arbortext Issue will be resolved before or very soon
after DITA 1.2

> reaches the final stages of approval.

> 

> Oxygen points to strict task because it uses the
TC-provided shells and

> modules without modification.

> 

> As far as publicizing the need for migration, I
think we can easily include

> an appendix to the 1.2 spec that lists migration
items and how to address

> them in moving from 1.1 to 1.2.

> 

> I don't think it's going to come as a surprise to
any 1.1 user that 1.2 is a

> significant change to DITA.

> 

> We also have the DITA Users news group as well as
the other channels

> used by the DITA Adoption TC.

> 

> Cheers,

> 

> E.

> 

> --

> Eliot Kimber

> Senior Solutions Architect

> "Bringing Strategy, Content, and Technology
Together"

> Main: 610.631.6770

> www.reallysi.com

> www.rsuitecms.com

On 11/13/09 3:26 PM, "Ogden, Jeff" 

I would also like to participate in the upgrade guide. FWIW I'm not sure
it should be part of the spec -- but a separate document the spec
references. 


--
Gershon

-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com] 
Sent: Friday, November 13, 2009 11:42 PM
To: Ogden, Jeff; Joann Hackos; Michael Priestley
Cc: dita; Park Seth-R01164
Subject: Re: [dita] strict task vs. general task vs. the file naming and
module rules

On 11/13/09 3:26 PM, "Ogden, Jeff" 

I'll sign up for user testing. That is, I'll walk through the guide
step-by-step to make sure an average user can complete the tasks with
the information provided.


-seth


--------------------------------------------
seth park
information architect
Freescale Semiconductor, Inc.
seth.park@freescale.com
512.895.2463

-----Original Message-----
From: Gershon Joseph (gerjosep) [mailto:gerjosep@cisco.com] 
Sent: Monday, November 16, 2009 4:11 AM
To: Eliot Kimber; Ogden, Jeff; Joann Hackos; Michael Priestley
Cc: dita; Park Seth-R01164
Subject: RE: [dita] strict task vs. general task vs. the file naming and
module rules

I would also like to participate in the upgrade guide. FWIW I'm not sure
it should be part of the spec -- but a separate document the spec
references. 


--
Gershon

-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com]
Sent: Friday, November 13, 2009 11:42 PM
To: Ogden, Jeff; Joann Hackos; Michael Priestley
Cc: dita; Park Seth-R01164
Subject: Re: [dita] strict task vs. general task vs. the file naming and
module rules

On 11/13/09 3:26 PM, "Ogden, Jeff" 

Eliot,



On the one hand you say:



> I don't think it's going
to come as a surprise to any 1.1 user that 1.2 is a significant change to DITA



and on the other you say:



> DITA 1.2 is fully
backward compatible with DITA 1.1



Even if DITA 1.2 is fully backward compatible with DITA
1.1 in some legalistic sense (I'm not agreeing that it is), I hope you can see
that some people might not be expecting "significant change" to
existing specializations/customizations when they upgrade to a new "compatible"
version of the spec.



   -Jeff



> -----Original Message-----

> From: Eliot Kimber [mailto:ekimber@reallysi.com]

> Sent: Friday, November 13, 2009 4:42 PM

> To: Ogden, Jeff; Joann Hackos; Michael Priestley

> Cc: dita; Park Seth-R01164

> Subject: Re: [dita] strict task vs. general task vs.
the file naming

> and module rules

> 

> On 11/13/09 3:26 PM, "Ogden, Jeff"
<jogden@ptc.com> wrote:

> 

> > Eliot wrote:

> >

> >> I don't think it's going to come as a
surprise to any 1.1 user that

> 1.2 is a

> >> significant change to DITA.

> 

> > It might if we continue to claim that DITA 1.2
is compatible with

> DITA 1.1.

> >

> > I still hope we do not go forward with option
(1), but if we do, I

> don't think

> > we can continue to claim that DITA 1.2 is
compatible with DITA 1.1

> and 1.0.

> > Instead I think we'll need to say something
like:

> >

> >

> >

> >
·         DITA 1.2 is mostly
compatible with DITA 1.1 and 1.0.

> >

> >
·         DITA 1.2 is largely
compatible with DITA 1.1 and 1.0.

> >

> >
·         DITA 1.2 is compatible
with DITA 1.1 and 1.0 except for the

> > following changes xxxx, xxxx, ..., and xxxx.

> >

> >
·         DITA 1.2 is compatible
with DITA 1.1 and 1.0 except for the

> items

> > listed in Appendix XX of the DITA 1.2
Architectural Specification.

> 

> I don't think that's fair--DITA 1.2 is fully
backward compatible with

> DITA

> 1.1 in that all conforming DITA 1.1 documents will
continue to be

> conforming

> DITA 1.2 documents.

> 

> There is nothing in the requirement for backward
compatibility that

> says we

> can't, for example, relax constraints. We cannot
*add* constraints.

> 

> I think there would be more room for complaint if we
hadn't added the

> constraint module for task. But we did. Anyone can
use it and most will

> use

> it automatically without realizing it.

> 

> We're fixing a serious design flaw in DITA 1.0
(overconstrained task)

> and

> doing it in such a way that the majority of users
will probably never

> even

> notice and the ones who do notice have a ready fix
at hand (the task

> constraint module).

> 

> > Is anyone working on a draft of the
"upgrade guide" chapter or

> document that

> > we've said is needed?

> 

> I will certainly sign up to contribute if no-one
else has volunteered.

> 

> Cheers,

> 

> E.

> 

> --

> Eliot Kimber

> Senior Solutions Architect

> "Bringing Strategy, Content, and Technology
Together"

> Main: 610.631.6770

> www.reallysi.com

> www.rsuitecms.com

 



  

  

  From: Ogden, Jeff [mailto:jogden@ptc.com]
Sent: Friday, November 13, 2009 4:27 PM
To: Eliot Kimber; 
  Joann Hackos; Michael Priestley
Cc: dita; Park 
  Seth-R01164
Subject: RE: [dita] strict task vs. general task vs. the 
  file naming and module rules


  

  

  

  
I'm thinking of starting a 
  betting pool about if DITA 1.2 will be an officially approved OASIS standard 
  before the next major release of Arbortext Editor comes out. The TC and OASIS 
  have roughly 11 months to get this done to win that race. At this point it is 
  not clear which side of this bet I’ll take myself.
  

  
    
  -Jeff 
  
 
A 
lot of our time consuming work now is on the spec. Would it speed the process if 
we plan to make additional spec refinements during and after public review? I 
don't know the process, but don't we expect that we might have changes come out 
of public review?  Planning for that, couldn't we identify some of the 
known readability and presentation issues that we would like to make better, and 
plan to do them in that time frame so that we can concentrate on the accuracy 
and substance issues before release for public review?
 
    /Bruce

  
 

I'm not sure if there is an OASIS policy on this or not, but I
don't think we should issue a spec for public review unless we think it is
ready for public review, and that means that we as a TC think it is ready for
publication except for truly editorial nits.  And the kind of wholesale
rewriting and redefining of terminology--to say nothing of the issue of general
versus strict task--go way beyond editorial nits.



So I would be against issuing the spec for public review until it
is really ready for it.  And we still have to do our last non-public review first.



paul









From: Bruce Nevin
(bnevin) [mailto:bnevin@cisco.com]

Sent: Friday, 2009 November 13 15:54

To: dita

Subject: [dita] Release date







 











From: Ogden, Jeff [mailto:jogden@ptc.com]

Sent: Friday, November 13, 2009 4:27 PM

To: Eliot Kimber; Joann Hackos; Michael Priestley

Cc: dita; Park Seth-R01164

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



I'm thinking of starting a
betting pool about if DITA 1.2 will be an officially approved OASIS standard
before the next major release of Arbortext Editor comes out. The TC and OASIS
have roughly 11 months to get this done to win that race. At this point it is
not clear which side of this bet I’ll take myself.



    -Jeff 

 



A lot of our time consuming work now is on the spec. Would it
speed the process if we plan to make additional spec refinements during and
after public review? I don't know the process, but don't we expect that we
might have changes come out of public review?  Planning for that, couldn't
we identify some of the known readability and presentation issues that we would
like to make better, and plan to do them in that time frame so that we can
concentrate on the accuracy and substance issues before release for public
review?

 

    /Bruce



 

Paul,
 
I think we're in 
agreement. Do you mean something different from "readability and 
presentation issues" when you say "editorial nits"?
 
    /Bruce



  

  

  From: Grosso, Paul [mailto:pgrosso@ptc.com]
Sent: Saturday, November 14, 2009 10:43 AM
To: 
  dita
Subject: RE: [dita] Release date


  

  

  
I'm not sure 
  if there is an OASIS policy on this or not, but I don't think we should issue 
  a spec for public review unless we think it is ready for public review, and 
  that means that we as a TC think it is ready for publication except for truly 
  editorial nits.  And the kind of wholesale rewriting and redefining of 
  terminology--to say nothing of the issue of general versus strict task--go way 
  beyond editorial nits.
  

  
So I would be 
  against issuing the spec for public review until it is really ready for 
  it.  And we still have to do our last non-public review 
  first.
  

  
paul
  

  

  

  

  
From: Bruce Nevin 
  (bnevin) [mailto:bnevin@cisco.com]
Sent: Friday, 2009 November 13 
  15:54
To: dita
Subject: [dita] Release 
  date
  

  
 
  

    

    

    

    
    
From: Ogden, Jeff 
    [mailto:jogden@ptc.com]
Sent: Friday, November 13, 2009 4:27 
    PM
To: Eliot Kimber; Joann Hackos; Michael Priestley
Cc: 
    dita; Park Seth-R01164
Subject: RE: [dita] strict task vs. general 
    task vs. the file naming and module rules
    

    
I'm thinking of starting 
    a betting pool about if DITA 1.2 will be an officially approved OASIS 
    standard before the next major release of Arbortext Editor comes out. The TC 
    and OASIS have roughly 11 months to get this done to win that race. At this 
    point it is not clear which side of this bet I’ll take 
    myself.
    

    
    
    -Jeff 
    
 
  
A 
  lot of our time consuming work now is on the spec. Would it speed the process 
  if we plan to make additional spec refinements during and after public review? 
  I don't know the process, but don't we expect that we might have changes come 
  out of public review?  Planning for that, couldn't we identify some of 
  the known readability and presentation issues that we would like to make 
  better, and plan to do them in that time frame so that we can concentrate on 
  the accuracy and substance issues before release for public 
  review?
  
 
  
    
  /Bruce
  

    
 

I'm with Paul. I consider that at public review, only
"mechanicals" (spelling, punctuation, minor markup refinement) should be
found by anyone reviewing--all substantive wording edits including
"readability" should already be complete. Markup improvements might change
the presentation, but should not alter the discourse, which is what we want
the public reviewers to concentrate on.

Regards,
--
Don Day
Chair, OASIS DITA Technical Committee
Architect, Lightweight DITA Publishing Solutions
Email: dond@us.ibm.com
11501 Burnet Rd. MS9033E015, Austin TX 78758
Phone: +1 512-244-2868 (home office)

"Where is the wisdom we have lost in knowledge?
 Where is the knowledge we have lost in information?"
   --T.S. Eliot


                                                                                                                
  From:       "Bruce Nevin (bnevin)" 

AFAIK 
the OASIS procedure states that a spec sent out for public review must be final. 
Minor updates to language to clarify things is permitted, as are fixes to typos 
etc. However, any change to the normative spec that is not just cleaning up the 
language requires the process to be started again. I think it's unfair to submit 
an incomplete spec to public review, since we would need to resubmit it after we 
finish our spec development work. It would be unfair on our TC admin, who has to 
do quite a bit of behind the scenes work in order to release a spec into the 
approval workflow, and it would also be unfair to the general OASIS members who 
would review the incomplete spec and then be asked to re-review it a few months 
later. 
 
The TC 
needs to finish our design and development work and complete the spec 
documentation before we initiate the OASIS review workflow.
 
--
Gershon
 




From: Grosso, Paul [mailto:pgrosso@ptc.com]
Sent: Saturday, November 14, 2009 5:43 PM
To: 
dita
Subject: RE: [dita] Release date




I'm not sure if 
there is an OASIS policy on this or not, but I don't think we should issue a 
spec for public review unless we think it is ready for public review, and that 
means that we as a TC think it is ready for publication except for truly 
editorial nits.  And the kind of wholesale rewriting and redefining of 
terminology--to say nothing of the issue of general versus strict task--go way 
beyond editorial nits.

So I would be 
against issuing the spec for public review until it is really ready for 
it.  And we still have to do our last non-public review 
first.

paul




From: Bruce Nevin 
(bnevin) [mailto:bnevin@cisco.com]
Sent: Friday, 2009 November 13 
15:54
To: dita
Subject: [dita] Release 
date

 

  

  

  

  
  
From: Ogden, Jeff 
  [mailto:jogden@ptc.com]
Sent: Friday, November 13, 2009 4:27 
  PM
To: Eliot Kimber; Joann Hackos; Michael Priestley
Cc: 
  dita; Park Seth-R01164
Subject: RE: [dita] strict task vs. general 
  task vs. the file naming and module rules
  

  
I'm thinking of starting a 
  betting pool about if DITA 1.2 will be an officially approved OASIS standard 
  before the next major release of Arbortext Editor comes out. The TC and OASIS 
  have roughly 11 months to get this done to win that race. At this point it is 
  not clear which side of this bet I’ll take myself.
  

  
    
  -Jeff 
  
 
A 
lot of our time consuming work now is on the spec. Would it speed the process if 
we plan to make additional spec refinements during and after public review? I 
don't know the process, but don't we expect that we might have changes come out 
of public review?  Planning for that, couldn't we identify some of the 
known readability and presentation issues that we would like to make better, and 
plan to do them in that time frame so that we can concentrate on the accuracy 
and substance issues before release for public review?
 
    
/Bruce

  
 

We should submit a version for
public review that we feel is final and ready to become a standard.  If we
need to make changes in response to comments received during the public review
to improve or clarify the language, we can do that, but we shouldn’t
submit something knowing that we want to make more changes.



Several of the issues that are
pending before  the TC are quite substantive and it feels as if more such
issues are raised each week.  We either need to find a way to defer those
items to DITA 1.3 or we need to take the time to deal with them well.  



    -Jeff









From: Gershon Joseph
(gerjosep) [mailto:gerjosep@cisco.com]

Sent: Monday, November 16, 2009 5:20 AM

To: Grosso, Paul; dita

Subject: RE: [dita] Release date









AFAIK the OASIS procedure states that a spec sent out for public
review must be final. Minor updates to language to clarify things is permitted,
as are fixes to typos etc. However, any change to the normative spec that is
not just cleaning up the language requires the process to be started again. I
think it's unfair to submit an incomplete spec to public review, since we would
need to resubmit it after we finish our spec development work. It would be
unfair on our TC admin, who has to do quite a bit of behind the scenes work in
order to release a spec into the approval workflow, and it would also be unfair
to the general OASIS members who would review the incomplete spec and then be
asked to re-review it a few months later. 





 





The TC needs to finish our design and development work and
complete the spec documentation before we initiate the OASIS review workflow.





 



--

Gershon



 











From: Grosso, Paul [mailto:pgrosso@ptc.com]

Sent: Saturday, November 14, 2009 5:43 PM

To: dita

Subject: RE: [dita] Release date

I'm not sure if there is an OASIS policy on this or not, but I
don't think we should issue a spec for public review unless we think it is
ready for public review, and that means that we as a TC think it is ready for
publication except for truly editorial nits.  And the kind of wholesale
rewriting and redefining of terminology--to say nothing of the issue of general
versus strict task--go way beyond editorial nits.



So I would be against issuing the spec for public review until it
is really ready for it.  And we still have to do our last non-public
review first.



paul









From: Bruce Nevin
(bnevin) [mailto:bnevin@cisco.com]

Sent: Friday, 2009 November 13 15:54

To: dita

Subject: [dita] Release date







 











From: Ogden, Jeff [mailto:jogden@ptc.com]

Sent: Friday, November 13, 2009 4:27 PM

To: Eliot Kimber; Joann Hackos; Michael Priestley

Cc: dita; Park Seth-R01164

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



I'm thinking of starting a
betting pool about if DITA 1.2 will be an officially approved OASIS standard
before the next major release of Arbortext Editor comes out. The TC and OASIS
have roughly 11 months to get this done to win that race. At this point it is
not clear which side of this bet I’ll take myself.



    -Jeff 

 



A lot of our time consuming work now is on the spec. Would it
speed the process if we plan to make additional spec refinements during and
after public review? I don't know the process, but don't we expect that we
might have changes come out of public review?  Planning for that, couldn't
we identify some of the known readability and presentation issues that we would
like to make better, and plan to do them in that time frame so that we can
concentrate on the accuracy and substance issues before release for public
review?

 

    /Bruce



 

Hi everyone,

  Just to clarify about public reviews. There are two approaches. The first is a TC who is trying to garner input from the community to improve the specification. In that scenario, multiple public reviews are likely (and encouraged). Specific areas can be called out in the review announcement to highlight spots where feedback is especially appreciated.

  The other approach is that the spec is thought to be done by the TC and after several internal reviews is finally submitted for public review. Of course the public may still come back with lots of feedback but typically the TC is less likely to act on such feedback unless it relates to minor changes, language clarification, typos, etc. More substantive changes are either rejected or put on the queue for the next release.

  There is no hard and fast rule. While the former may take a bit more work on my part, I think (personal opinion here) it's validation of the openness of OASIS and the ability for anyone to contribute to the work. 

  Hopefully that helps clarify.

Regards,

Mary



Mary P McRae
Director, Standards Development
Technical Committee Administrator
OASIS: Advancing open standards for the information society
email: mary.mcrae@oasis-open.org 
web: www.oasis-open.org
twitter: @fiberartisan  #oasisopen
phone: 1.603.232.9090

Standards are like parachutes: they work best when they're open.



On Nov 16, 2009, at 5:19 AM, Gershon Joseph (gerjosep) wrote:

AFAIK the OASIS procedure states that a spec sent out for public review must be final. Minor updates to language to clarify things is permitted, as are fixes to typos etc. However, any change to the normative spec that is not just cleaning up the language requires the process to be started again. I think it's unfair to submit an incomplete spec to public review, since we would need to resubmit it after we finish our spec development work. It would be unfair on our TC admin, who has to do quite a bit of behind the scenes work in order to release a spec into the approval workflow, and it would also be unfair to the general OASIS members who would review the incomplete spec and then be asked to re-review it a few months later.
 
The TC needs to finish our design and development work and complete the spec documentation before we initiate the OASIS review workflow.
 
--
Gershon
 

From: Grosso, Paul [mailto:pgrosso@ptc.com] 
Sent: Saturday, November 14, 2009 5:43 PM
To: dita
Subject: RE: [dita] Release date

I'm not sure if there is an OASIS policy on this or not, but I don't think we should issue a spec for public review unless we think it is ready for public review, and that means that we as a TC think it is ready for publication except for truly editorial nits.  And the kind of wholesale rewriting and redefining of terminology--to say nothing of the issue of general versus strict task--go way beyond editorial nits.
So I would be against issuing the spec for public review until it is really ready for it.  And we still have to do our last non-public review first.
paul
From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com] 
Sent: Friday, 2009 November 13 15:54
To: dita
Subject: [dita] Release date
 
From: Ogden, Jeff [mailto:jogden@ptc.com] 
Sent: Friday, November 13, 2009 4:27 PM
To: Eliot Kimber; Joann Hackos; Michael Priestley
Cc: dita; Park Seth-R01164
Subject: RE: [dita] strict task vs. general task vs. the file naming and module rules
I'm thinking of starting a betting pool about if DITA 1.2 will be an officially approved OASIS standard before the next major release of Arbortext Editor comes out. The TC and OASIS have roughly 11 months to get this done to win that race. At this point it is not clear which side of this bet I’ll take myself.
    -Jeff 
 
A lot of our time consuming work now is on the spec. Would it speed the process if we plan to make additional spec refinements during and after public review? I don't know the process, but don't we expect that we might have changes come out of public review?  Planning for that, couldn't we identify some of the known readability and presentation issues that we would like to make better, and plan to do them in that time frame so that we can concentrate on the accuracy and substance issues before release for public review?
 
    /Bruce
 

Jeff asked:
>Michael, can you explain why the naming
model matters so much?  I just don’t see it as 
>very important since it only applies
to some modules and not to others.

I'm lumping several issues together,
so I'll try to tease them out:

- we have modularization rules that
keep constraints and vocabulary modules separate. Proposal 2 breaks those
rules. I'm still not sure of all the implications of that breakage. If
the proposal 2 task.mod is a pull-together of the generaltask.mod plus
the constraints mod file, for example, then there may be existing shell
DTDs or XSDs in which the combined order results in an invalid doctype.
If instead it is a copy of generaltask.mod with a different set of content
models, then that means we will have dual maintenance on those element
definitions, with I'm not sure what extra risks and consequences.

- we have public identifiers that point
to the latest modules - for example:
  <public publicId="-//OASIS//ELEMENTS
DITA Task//EN"
          uri="task.mod"/>
That will now be pointing at an invalid
and deprecated module according to our standard module scheme. Anyone assembling
a new shell doctype using 1.1-level information or tutorials will be picking
up the deprecated module by default. They may figure out the problem at
some point, or they may not. But I think it's reasonable to assume that,
if we make the default identifiers for task.mod point to something we deprecate,
we will have a lot more deprecated shells in the future. 

- as Robert pointed out in his summary,
these concerns apply whether you change the names or change the URIs. Either
way, you are making the default be to pick up a badly modularized vocabulary
file that will be immediately deprecated and that will either require dual
maintenance or potentially render some shell combinations invalid. And
I think changing the default will likely affect future task specializers,
not just existing task specializations.

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:
"Gershon Joseph (gerjosep)"
<gerjosep@cisco.com>, Michael Priestley/Toronto/IBM@IBMCA, "JoAnn
Hackos" <joann.hackos@comtech-serv.com>

Cc:
"dita" <dita@lists.oasis-open.org>,
"Park Seth-R01164" <R01164@freescale.com>

Date:
11/16/2009 06:48 AM

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





Gershon wrote:
> Let's
do the right thing, and address the problem via education and documentation
 
We don’t have a consensus on what the right
thing to do is.  We can either keep talking or we can vote.  I
think it is time to vote.
 
Michael wrote:
> 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, can you explain why the naming
model matters so much?  I just don’t see it as very important since
it only applies to some modules and not to others.
 
While srating his preference for option
1, Bruce wrote:
> ...
It’s the only way to be absolutely sure to avoid unforeseen consequences
that might flow from the workarounds in option 2.
 
I want to avoid the now foreseen consequences
from option 1.  That seems more important than worrying about as yet
unforeseen consequences from option 2 that may or may not arise at some
point in the future.  But, if we are going to worry about the unknown
future, there is always the possibility of more unforeseen consequences
from option 1.
 
   -Jeff
 
 
From: Gershon Joseph (gerjosep) [mailto:gerjosep@cisco.com]


Sent: Monday, November 16, 2009 4:59 AM

To: Michael Priestley; JoAnn Hackos

Cc: dita; Park Seth-R01164

Subject: RE: [dita] strict task vs. general task vs. the file naming
and module rules
 
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