RE: [dita] A different model for handling backwards compatibility (sorrylong)

[Robert D Anderson <robander@us.ibm.com>]

Here is the TC-approved description of what constitutes backwards
incompatible changes for the 1.* releases:
http://www.oasis-open.org/committees/download.php/13781/notesonbackwardscompatibility.html

It does not mention deprecation in the list of forwards-compatible changes,
but it also says that the list is not exhaustive. The exhaustive list of
backwards-incompatible changes also does not mention deprecation. Given
that deprecating an attribute/element/practice does not violate any of the
rules in this document, it should be legal, as long as we do not actually
remove the item in a 1.* release.

I could update that list again to include deprecation as one of the
compatible changes, but that would mean spending TC time discussing and
approving the document. Another alternative is just to agree that this
falls under the non-exhaustive list of legal changes.

Robert D Anderson
Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787


                                                                           
             "JoAnn Hackos"                                                
             <joann.hackos@com                                             
             tech-serv.com>                                             To 
                                       "Paul Prescod"                      
             03/25/2006 11:30          <paul.prescod@blastradius.com>,     
             AM                        <dita@lists.oasis-open.org>         
                                                                        cc 
                                                                           
                                                                   Subject 
                                       RE: [dita] A different model for    
                                       handling backwards compatibility    
                                       (sorry long)                        
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           




I agree with Paul's point. Now is the time to make changes that are not
backward compatible, not five years from now when more and more
organizations (we assume) will incorporate DITA.
JoAnn

-----Original Message-----
From: Paul Prescod [mailto:paul.prescod@blastradius.com]
Sent: Saturday, March 25, 2006 8:36 AM
To: dita@lists.oasis-open.org
Subject: [dita] A different model for handling backwards compatibility
(sorry long)

After some new thought, I think that the DITA community's approach to
backwards compatibility is expedient but long-term not efficient.

Let's say that "someday" we are going to make a backwards-incompatible
change like changing the element name syntax or the ID syntax. Here is
the expedient approach we use today:

 * We can't change this today

 * let's not think about it

 * let's wait for more and more content to be made in the old way

 * when we get around to wanting to change it, it will be much harder or
impossible

Result: backwards compatible changes will almost never happen. The
result of the result: DITA will accumulate more and more cruft over
time.

My alternate proposal:

 * We can't change this today

 * think about and debate it -- do cost benefit analsys ("is xml:id
right for DITA? Is the benefit worth the high cost of implementing it?")

 * define the new way and document it as quickly as possible

 * implement the new way alongside the old way as quickly as possible
("Every DITA element can have either an 'id' or 'xml:id' attribute --
xml:id is preferred")

 * ask customers to use the new way instead of the old way ("The 'id'
attribute is deprecated")

 * remove the old way -- years or even decades down the road

This is a very proven mechanism for implementing backwards incompatible
changes. Using basically this technique, many companies have migrated
from K&R C to ANSI C to C++. The sooner we figure out what backwards
incompatible changes we need to make, the longer we can overlap the new
way and the old way and the more we can ease the transition for our
customers. Delaying it just increases the amount of content done in the
"old way" and makes the transition that much more painful.

This is ESPECIALLY true for DITA, which is just STARTING to take off
worldwide. DITA's growth will be greatest in the next year and in
retrospect (nobody's fault) I'm sorry we haven't been more aggressive
about figuring out what backwards compatible changes we need. (on the
other hand, a year ago only IBMers understood DITA, so the process would
have been difficult)

I propose that we go through this process after DITA 1.1. It's a
separate issue WHICH backwards compatible changes to schedule, but my
main point is: let's stop deferring them. Backwards incompatibility is
an argument for doing something sooner.

 Paul Prescod