dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [dita] strict task vs. general task vs. the file naming and module rules
- From: "Gershon Joseph (gerjosep)" <gerjosep@cisco.com>
- To: "Michael Priestley" <mpriestl@ca.ibm.com>, "JoAnn Hackos" <joann.hackos@comtech-serv.com>
- Date: Mon, 16 Nov 2009 01:58:34 -0800
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
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]