[xtm-wg] Revised style guide

[Sam Hunting <sam_hunting@yahoo.com>]

Attached is a revised Style Guide for the XTM specs, after feedback
from James Mason and Peter Jones.

Comments welcome -- and Happy New Year!

Sam Hunting

=====
<!-- "To imagine a language is to imagine a form of life."
     - Ludwig Wittgenstein, Philosophical Investigations -->

__________________________________________________
Do You Yahoo!?
Yahoo! Photos - Share your holiday photos online!
http://photos.yahoo.com/
-------------------------- eGroups Sponsor -------------------------~-~>
eLerts
It's Easy. It's Fun. Best of All, it's Free!
http://click.egroups.com/1/9699/0/_/337252/_/978298816/
---------------------------------------------------------------------_->

To Post a message, send it to:   xtm-wg@eGroups.com

To Unsubscribe, send a blank message to: xtm-wg-unsubscribe@eGroups.com
Style Guide for XTM Specifications
----------------------------------

Sam Hunting
This posting: 2000-12-31

Reviewers:
    Dr. James Mason
    Peter Jones

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 (see point 9), 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. 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".)

8. 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.
      
      These distinctions may also be made with formatting and/or
      markup to be determined (which will aid translation).

9. In the glossary:

    * Avoid lists of different senses for a single term (1,2,3...n).
      These lists may be symptoms of discourse conflation. Make
      each list item a separate definition.
      
      NOTE: Since elements are formatted <element>, this may
      mean that some obvious terms are not glossed.
      
    * Terms should be formatted in the glossary as they are
      formatted in the text.
      
    * The ideal definition is a single short paragraph.
      Therefore:
      
      Do not include matter best left in the prose of the
      specification. Define, but do not explain, justify,
      contrast with alternatives, etc.

10. The idea behind variant: For purposes of computation.
      
Copy guidelines
---------------

1. 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.)   

2. "Constraints on", not "constraints of"

3. Links "assert"

4. "composed of" is the inverse of "contains"

5. Avoid "comprise"
        
6. An instanceOf element does not refer to a class,
   it references a class text.

7. Check that key words of RFC 2119 are properly used "MUST"
   etc.

8. Graph terminology must be consistent throughout: nodes, arcs,
   labelled arcs.
            
9. "reify" is verboten.

10. Watch for anthropromorphism, e.g. topic map engine
    being "aware," "know", etc.           
            
11. Capitalize letter after "NOTE:" colon if complete sentence trails

12. Information from resources internal to the TM "provide"

13. Information from resources external to the TM "supply"

14. Topics "declare" subjects.

15. Never "relation" (database connotations). Always "relationship"