If bookmap is fundamentally flawed (which I cannot deny!), I strongly suggest we develop a parallel new publication map in DITA 2.0, with documentation that the legacy bookmap will be deprecated in DITA 3.0.
I m happy to lead the effort on the next-gen publication map, assuming I can gather everyone s input and ideas.
Kris, feel free to add this item to a future agenda. If there is any documentation on the known flaws of bookmap and ideas that have been suggested for the new publication map, please point me to them.
Gershon
From: <
dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <
kris@eberleinconsulting.com>
Date: Tuesday, 3 December 2019 at 17:22
To: "Wegmann, Frank" <
Frank.Wegmann@softwareag.com>, "dita@lists.oasis-open.org" <
dita@lists.oasis-open.org>
Subject: Re: [dita] Stage three: #29 Bookmap update -- Ready for TC consideration
Two other considerations here:
The TC hoped to include a new publication map for DITA 2.0. Whether or not we will manage to do this is an open question ...
Because we considered the design of bookmap to be fundamentally flawed, we did not want to redesign it. But because we know bookmap is used heavily, we wanted to add some critical functionality. This is the rationale for updating bookmap without breaking backwards
compatibility.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype)
On 12/3/2019 9:21 AM, Wegmann, Frank wrote:
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!
Frank
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.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com +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.
See:
Stage two proposal for #29:
https://lists.oasis-open.org/archives/dita/201910/msg00097.html DITA 2.0 process:
https://wiki.oasis-open.org/dita/DITA_2.0_Proposal_Process_DRAFT (ignore fact that URL contains the word DRAFT)
</kje>
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!
<kje>Thanks.</kje>
Gershon
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 --
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com +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 --------------------------------------------------------------------- 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