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

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-adoption message

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


Subject: Some coments on our documents [was: [dita-adoption] OASIS DITA Adoption TC -- Agenda 20 July 2009]


My understanding is that the feature writups that our DITA Adoption TC
creates are to explain features and best practices to DITA users, not
to implementors.  As such, it seems inappropriate for these documents
to say things like "processors should...."  Rather, we should be
phrasing 
things as "users should...." 

> -----Original Message-----
> From: Joann Hackos [mailto:joann.hackos@comtech-serv.com]
> Sent: Sunday, 2009 July 19 18:20
> To: DITA Adoption TC
> Subject: [dita-adoption] OASIS DITA Adoption TC -- Agenda 20 July 2009


> 
> Kara Warburton's version:
> http://www.oasis-open.org/apps/org/workgroup/dita-
> adoption/download.php/33197/GlossarySpecializationBestPractice-
> rev2jth%5B2%5D.doc

Section 6.1 defines some fairly detailed processing.  I don't think 
this is appropriate in this document.  (I don't even think it is
appropriate in the description of the abbreviated-form in the
language spec, but that's another issue.)  I think section 6.1 
should be rewritten to talk to users instead of implementors,
and I'm not sure the level of detail here is necessary.  

If we are giving advice to users, then it should be phrased:

 A writer uses the <abbreviated-form> element with a keyref 
 attribute to refer to a glossentry topic from the text.
 DITA processors are expected to render this element using
 the appropriate replacement term defined in the referenced
 glossary entry depending on context of the term reference.

[The last para of 6.1 has "glossy entry" which should probably
be "glossary entry".]

Section 6.2 says "the publishing process should create published 
entries according to the particular style of the implementer".
I'm not sure that phrase says anything useful, and it isn't
providing any direction to the user in any case.  And getting
down to mentioning separating things by bullets or numbers is
way too far into details of output style that aren't part of
DITA at all.  How a user decides to style a glossary is not
something we should be discussing--that is a stylesheet issue.

I think section 6.2 should be renamed "Example" or some such,
and then it should just consist of the second half of the 
current section starting with the paragraph that begins
"The following examples...."

paul



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