RE: [dita] Terminology for the DITA 1.2 spec

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

Eliot, it's awfully good of you not to take umbrage at the implication
that your writing is unclear. That was an unintended side effect of the
main point about accuracy in the reader depending on readability in
addition to depending on accuracy in the writer. And the fundamental
purpose of the topic I wrote (now under review) was to provide an
overview with all the detailed topics about keys, conref, etc.
accessible from that one place by means of related-links. It was only in
conversation with you that we decided to merge it with the conref topic
conref.dita which you had written. So this is to set the record
straight, clear your good name as a writer, apologize for the unintended
slur, and thank you for your gracious response.

	/Bruce

> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Tuesday, November 10, 2009 2:19 PM
> To: Bruce Nevin (bnevin); dita
> Subject: Re: [dita] Terminology for the DITA 1.2 spec
> 
> I agree that accurate but hard-to-understand text doesn't 
> necessarily help.
> I try to write things as clearly as I can but I realize I 
> don't always achieve that. 
> 
> The back and forth that Bruce and I had is what we need in 
> order to achieve a result that is both technically accurate 
> and as readable as possible.
> That's hard work. My point on the call today is that if we 
> run out of time to do that work, accuracy has to win.
> 
> Keys in particular is something that has to be right in the 
> spec if there is going to be any hope of correct 
> implementation and interoperable implementations. That's one 
> reason I'm focusing a lot of energy on implementing keyref 
> myself as a way of testing the spec, as well as a way of 
> providing value to my clients and constituents. In addition, 
> I have nearly 20 years experience with standards-based 
> hyperlinking. I was the primary working editor of HyTime 2. I 
> know what a hand-waving linking standard looks like (HyTime 
> 1) and I know what it takes to create a solid linking standard.
> It's fiddly, technical stuff that requires a degree of 
> pedantry not necessarily required in the rest of an 
> application like DITA. It is one of the few places in DITA 
> where there really is only one right answer and the spec has 
> to be written in such a way that only one right answer is 
> possible based on the language of the spec. That's hard to 
> do. I know that DITA isn't HyTime but that part of the DITA 
> spec that deals with linking and addressing needs a level of 
> rigor the DITA has not had to date, which is simply a 
> reflection of its original life as an IBM internal 
> application, not a standard. 
> 
> Cheers,
> 
> Eliot
> 
> On 11/10/09 11:28 AM, "Bruce Nevin (bnevin)" <bnevin@cisco.com> wrote:
> 
> > I produced IMO an instance of what Eliot was describing as 
> an effort 
> > at readability that resulted in inaccuracy.
> > I sent it to him first. His technical review corrected my 
> > misunderstandings. That's the role of technical review.
> > Others are performing their technical review of it this week.
> > 
> > The point here is that when something that is accurate when 
> properly 
> > read is difficult to read properly, the reader's 
> understanding of it 
> > may be inaccurate. It's of questionable benefit that some text is 
> > completely accurate (by some set of criteria) if 
> intelligent readers 
> > understand it in a way that is inaccurate.
> > 
> > So it's not quite so simple as a version of the classic trilemma 
> > "cheap, fast, good, pick two", restated as I heard it on 
> today's call 
> > as "readable, on schedule, accurate, pick two". Accurate reading is 
> > contingent on readability in a way that "cheap" is not 
> contingent on 
> > "good".
> > 
> > /Bruce
> > 
> > 
> ---------------------------------------------------------------------
> > 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
> > 
> 
> -- 
> 
> 
>