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