OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RE: [dita] Stage three: #29 Bookmap update -- Ready for TC consideration

Hi Kris et al.


This bookmap update is the first proposal Iâve read now. Being new to the committee, I also wondered home some decisions have been made, but then Kris confirmed my suspicionsin her replies that it would be appropriate to study the previous stage proposals before raising my voice.


What I can say is that I generally appreciate the careful stance on breaking backward compatibility. The less hard the migration path, the less work it means to adapt production and reeducate authors, if you have dozens of them spread globally with hundreds of bookmaps, like we do. Iâm sure Robert is very much aware of a practitionerâs position like this.


Of course, progress needs to be made, and I especially welcome the addition of ditavalref to the bookmap as well as the introduction of the mapresources element. And, furthermore, the improved specification text by adding âProcessing expectationsâ.


Thank you for this extension of the bookmap!



From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> On Behalf Of Kristen James Eberlein
Sent: Monday, December 2, 2019 4:35 PM
To: dita@lists.oasis-open.org
Subject: Re: [dita] Stage three: #29 Bookmap update -- Ready for TC consideration


Hi, Gershon.

Please see my comments below.


Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 622-1501; kriseberlein (skype)

On 12/2/2019 9:17 AM, Gershon Joseph wrote:

Hi all,


I have reviewed this proposal and have a few comments (they are general comments not specifically related to this proposal. Excuse me if any of these things have been discussed in my absence from the TC, in which case just refer me to the minutes or other documentation.


Point #1

This proposal does not state why the change is being done. Whatâs the motivation for this change? Whatâs the business case? I can think of a couple, but I think the proposal should mention the business or technical need driving the change. Then this text could be lifted as-is to the documentation of the standard, which should make life easier for the authors of the eventual standard.

<kje>This is covered in the stage two proposal. It would be good if you familiarized yourself with the stage 1, stage 2, and stage processes. We put considerable time in implementing this new process for DITA 1.3 and revising it for DITA 2.0; we are pretty satisfied with it.

I'm very glad to see you back participating on the TC, Gershon, but you will have some catching up to do! We've changed a lot of processes since I became chair.



Point #2

Why are we concerned about keeping backward compatibility in a major release? The TC has a huge, once-in-a-lifetime opportunity to fix and improve things that we could not do with any minor release of the standard. If there is a better way to achieve the desired outcome, I suggest we do it now and document any backward incompatibility we introduce. Iâm concerned about making the DTD files more complex simply for the sake of backwards compatibility when weâre doing a major release.

<kje>DITA 2.0 is our very first backwards INCOMPATIBLE release. This has scared many people in the committee. Accordingly, we are committed to documenting backwards-incompatible stuff carefully. We also consider how big of an impact a change would have and whether it's worth it.

In general, we're doing a whole lot of clean up and implementing a lot of changes to previous design decisions that ended up being less than optimal.</kje>


Point #3

Point #2 is a good Segway into this concern. The standard says the XSDs are the normative standard, but our proposals talk about DTDs almost exclusively. All of our content model discussions are based on how to achieve the outcome via DTDs. If the XSD schema is normative, letâs focus our discussion on the XSD implementation and optimize that. At this time, the XSDs are essentially reverse-engineered DTDs, and donât take full opportunity of XSD functionality. For DITA 2.0 I feel strongly we should re-architect the XSDs to fully embrace the schema functionality and best practices. Many vendors have raised this concern with me, so itâs not just me. <duck as Robert A throws a large heavy object in my direction/>

Seriously, Iâm not undermining the huge effort Robert and others put into the XSDs, I really do appreciate it. What Iâm suggesting is we take on an XSD re-architecture at this time before itâs too late.


<kje>Um ... No. You are missing facts. RNG is the normative grammar and has been so since 1.3. We will not be shipping XSDs for DITA 2.0, unless someone steps forward to create and test them. Firm decision made already by the TC.</kje>


Point #4

The formatting of figure titles is confusing. I keep thinking the figure title is a figure caption referring to the code sample above, due to the lack of space above the title and huge space below. The figure title actually refers to the figure below the title. I know this is OASIS style, but please, please letâs fix it!!

<kje>If you have specific changes to suggest, I'll point you to the relevant plug-in. It lives in a DITA TC Git repo.</kje>


Besides these gripes, I really like this proposal and see how it will make life easier for many users. I think weâd use it eventually at Mastercard (my current client at Precision Content).


This is a very well-written proposal. Job well done!






From: <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com>
Date: Sunday, 1 December 2019 at 16:43
To: DITA TC <dita@lists.oasis-open.org>
Subject: [dita] Stage three: #29 Bookmap update -- Ready for TC consideration


This proposal has been reviewed by:

  • Nancy Harrison, Individual member
  • Eliot Kimber, Individual member
  • Eric Sirois, IXIASOFT

The PDF is attached; the DITA source is available at http://tools.oasis-open.org/version-control/browse/wsvn/dita/trunk/DITA-2.0/stage-3/Issue-29-bookmap-update.dita


Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 622-1501; kriseberlein (skype)

--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

Software AG â Sitz/Registered office: UhlandstraÃe 12, 64297 Darmstadt, Germany â Registergericht/Commercial register: Darmstadt HRB 1562 - Vorstand/Management Board: Sanjay Brahmawar (Vorsitzender/Chairman), Dr. Elke Frank, John Schweitzer, Dr. Stefan Sigg, Arnd Zinnhardt; - Aufsichtsratsvorsitzender/Chairman of the Supervisory Board: Dr. Andreas Bereczky - http://www.softwareag.com

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]