Snapp Annotation Authoring Guidelines

The Schema Annotation element can be added to most XML Schema elements. It specifies schema comments, which serve as inline documentation for the XSD. This section outlines applicable points of style and usage.

General Annotation Guidelines

Period use. Annotations do not end in a period except when the annotation is multiple complete sentences.

The vs. A. When referring to an element or concept generally, prefer the article “the” element vs. “a” or "an" element. Thus “The student's email address.”

Style & Usage Guidelines

alphanumeric. No hyphen.

complex type. Lower case.

e.g. and i.e. E.g. means “for example.” I.e. means “that is.” Use a comma after each (not a semicolon). Thus “e.g.,” Prefer these abbreviations inside parenthesis and the written out words “for example” or “that is” or "such as" outside of parenthesis and in full sentences. If “e.g.” or “i.e.” is used to prefix a list of examples, don’t use “etc.” at the end of the list. Example: “The student's salutation (e.g., Mr., Ms.)”

for example. The rule of thumb is to use “e.g.” inside parenthesis and “for example” outside of parenthesis. Annotations should generally prefer “e.g.” when simply listing examples expresses the point well. However, “for example” may be used when the examples are part of a passage meant to illuminate the reader beyond a simple list, or when a conversational tone is useful, or as the introduction to a bulleted/numbered list. Lists of items preceded by "for example" may end in "etc."

school. Lower case.

student. Lower case.

website. We're catching up with the times, so not Web site.