[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: [xtm-wg] Style Guide for XTM specs: feedback please
These guidelines were developed empirically during the editing round that that preceded the release of core in DC. I'm posting them now in anticipation of the harmonization efforts underway to finalize the specs for Paris. Please comment, suggest revisions, etc. Are there any professional editors out there who would care to make this a true copy editing guide? Style Guide for XTM Specifications ---------------------------------- Sam Hunting This posting: 2000-12-12. Except as noted below, the Chicago Manual of Style is the authority for copy editing XTM documents. Style guidelines ---------------- 1. For clarity, the specs should have a uniform voice. For reference, here are a few of Strunk and White's Elementary Principles of composition. (A copy editing XTM would treat these as PSIs). If only I when writing were consistently able to: * Omit Needless Words. * Avoid a Succession of Loose Sentences. * Make the Paragraph the unit of Composition. * Use Definite, Specific, Concrete Language. * Keep Related Words Together. * Use the Active Voice. * Put Statements in Positive Form. * Express Coordinate Ideas in Similar Form. 2. For precision, never "subelement", container, subtree, etc. Use ancestry metaphors consistently throughout (a la xpointer axes). In reworking text for this rule, watch very carefully for discourse conflation (q.v.), eg, "a <topic> is a container for the name and ocscurrence characteristics of a single topic." No, it isn't. A <topic> element can "contain" only other elements or #PCDATA. The rule is designed to avoid such usages.) 3. For consistency, watch for parenthetical remarks or asides in prose that may contradict glossary definitions. 4. For simplicity or the appearance thereof, footnotes are deprecated. Integrate them into the text, put them into parentheses, move them, or remove them entirely. 5. For clarity, write to a uniform comprehension level. Slash words like "ineffable". ISOese is the last resort, not the first and best choice. Rework lawyerly phrases like "deemed", "regarded as", "considered to be". 6. For clarity, in the glossary, be explicit where a term does NOT have a corresponding element type. 7. The idea behind variant: For purposes of computation. 8. For subject identity: the key axis is "is" vs. "describes". Synonyms for "describe" that should be examined carefully include: * define * indicate * specify Try to reserve "indicate" only for that which, in itself, "indicates" a subject identity point. (instanceOf may therefore "indicate".) 9. In prose, for each string that is also a generic identifier, or close to one, carefully distinguish: a. ordinary prose "a topic is a subject of discourse" b. markup "a <topic> element" c. uml "the class of topics" d. processing "topic node" To some extent these distinctions are enabled by creating different sections for the different levels of discourse. However, particularly in the introductions to sections, ambiguity will occur. "discourse conflation" is the best term I have been able to come up with for this stylistic issue. It would be best to avoid discourse conflation with distinct vocabularies for a-d -- as for example, t-node, not topic node, in the Processing Model. This may not in all cases be possible. Copy guidelines --------------- 1. "Constraints on", not "constraints of" 2. Links "assert" 3. "composed of" is the inverse of "contains" 4. Avoid "comprise" 5. An instanceOf element does not refer to a class, it references a class text. 6. Check that key words of RFC 2119 are properly used. 7. Graph terminology must be consistent throughout: nodes, arcs, labelled arcs. 8. "reify" is verboten. 9. Watch for anthropromorphism, eg topic map engine being "aware." 10. Capitalize letter after "NOTE:" colon if complete sentence trails 11. Information from resources internal to the TM "provide" 12. Information from resources external to the TM "supply" 13. Topics "declare" subjects. 14. Never "relation" (database connotations). Always "relationship" 15. For clarity, use the serial comma. ("A, B, and C" is a list of three items. "A, B and B" may be construed as a list of 3, or possibly 2, items.) ===== <!-- "To imagine a language is to imagine a form of life." - Ludwig Wittgenstein, Philosophical Investigations --> __________________________________________________ Do You Yahoo!? Yahoo! Shopping - Thousands of Stores. Millions of Products. http://shopping.yahoo.com/ -------------------------- eGroups Sponsor -------------------------~-~> eGroups eLerts It's Easy. It's Fun. Best of All, it's Free! http://click.egroups.com/1/9698/0/_/337252/_/976735841/ ---------------------------------------------------------------------_-> To Post a message, send it to: xtm-wg@eGroups.com To Unsubscribe, send a blank message to: xtm-wg-unsubscribe@eGroups.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC