[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]