RE: [dita] Proposal: Allow <xref> within <shortdesc>

["Chris Nitchie" <chris.nitchie@oberontech.com>]

I've seen customers who are afraid to develop specializations because they
don't want to become "incompatible with DITA." I've tried to push back hard
against this complete misconception, with limited success. When you ship a
grammar with your standard, peoples' natural assumption is that that's *the*
grammar. Also, specializations are considered - sometimes correctly,
sometimes not, depending on the nature of the change - as costly to develop
and maintain.

All of which is to say, in principle, I agree with Eliot, and in order to
remain as flexible as possible the base doctypes need to be wide open, but
in practice, Kris has a point, in that people tend to ignore or deemphasize
the specialization aspect, especially at the beginning of the adoption
process.

A lot of people - myself included - tend to think of the technical content
DTDs as the 'base' doctypes, even though they're not. Towards the end of
DITA 1.2 we addressed this a bit with the addition of basetopic and basemap,
though they're not particularly emphasized. I think this is one reason
people resist specializations - the technical content doctypes aren't
presented as bases for specialization, they're presented as doctypes for
technical documentation, ready-made. The spec already does a pretty good job
of keeping discussion of the technical content-specific stuff in their own
sections, so I'm not sure there's much that could be done in the spec around
this, but the point that specialization is part and parcel of using DITA -
that it's the primary reason DITA exists - could maybe be emphasized more.

Chris

-----Original Message-----
From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf
Of Kristen James Eberlein
Sent: Tuesday, September 11, 2012 9:59 AM
To: Eliot Kimber
Cc: dita
Subject: Re: [dita] Proposal: Allow <xref> within <shortdesc>

Eliot, I knew that you and I would disagree on this issue. I'll be
interested to see what other folks who work primarily with an end-user base
have to say.

While I'd like to agree that our primary user group of concern is
"specializers" and "implementers," I think that for the DITA 1.x-level
releases we have a responsibility to look out for other communities,
including authors.

DITA 1.0 and DITA 1.1 were relatively simple and the spec relatively short.
With DITA 1.2, we added a lot of complexity -- some of which we are just
beginning to unravel and sort out -- and the spec became much more
inaccessible. I think we need to do a balancing act for the 1.x releases.

For this instance, simply constraining <xref> from the concept, task, and
reference shells might be an adequate answer. This might mean another item
for our DITA 1.3 proposal templates; for changes that will affect the base
vocabulary, do we need to add constraints to other TC-provided shells?

-- 
Best,
  
Kris
  
Kristen James Eberlein
Principal consultant, Eberlein Consulting
Co-chair, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)


On 9/11/2012 9:23 AM, Eliot Kimber wrote:
> On 9/11/12 6:54 AM, "Kristen James Eberlein" <kris@eberleinconsulting.com>
> wrote:
>
>> Given the role of the <shortdesc> for hover text and auto-generated link
text,
>> I think adding <xref> is inappropriate.
> Our point was that since you can already have links in shortdesc and thus
> processors need to account for them in hoverhelp or whatever, adding
<xref>
> doesn't change the problem.
>
> It is important to keep in mind that, at the base vocabulary level, our
> primary concern must be *specializers*, not authors. Authors are served by
> configured and specialized document types and it is certainly easy to
> constrain away xref if you do not want to allow it in <title> in your
> environment.
>
> But if there is *even one* legitimate requirement for xref in shortdesc
(and
> I certainly have that requirement in the Publishing space), then I contend
> we *must* allow it in the base content model for shortdesc.
>
> If we want to provide constraint modules for concept/task/reference that
> constrain xref out of shortdesc, I'm fine with that and will volunteer to
> define the constraints and update the TC-provided shells.
>
> But one of the historical problems with DITA as a base for wide use is
that
> many content models are over-constrained, disallowing satisfaction of
> legitimate requirements in order to reflect the practice of a specific
user
> community.
>
> We have to stop doing that.
>
> Cheers,
>
> E.

-- 
Best,
  
Kris
  
Kristen James Eberlein
Principal consultant, Eberlein Consulting
Co-chair, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)


---------------------------------------------------------------------
To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: dita-help@lists.oasis-open.org