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 modulerules
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: "JoAnn Hackos" <joann.hackos@comtech-serv.com>
- Date: Fri, 13 Nov 2009 10:35:23 -0500
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]