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: "Ogden, Jeff" <jogden@ptc.com>
- Date: Mon, 16 Nov 2009 09:13:07 -0500
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]