Documentation writing guidelines

Resources from the WWP

Phrase-level Encoding

As a project, decide which phrase-level elements from your documents you are want to tag. Review the WWP’s crib sheet above as well as the full list of TEI elements here. You might be particularly interested in the elements from the “Names and dates” module.

Questions to consider:

  • What phrase-level features are significant for your project (names of persons, places, organizations? quotations and titles? rhetorical and linguistic devices? dialogue?) and which elements can be used to tag those phenomena?
  • Where might you use @type to capture additional details about the elements in your encoded texts?
  • What values do you want to use with @type?
  • Are there any elements that you would like to use but that are not provided by the TEI? If so, you can use @type with a constrained set of values on an appropriate “generic” element. See the instructions here.

Organizing your texts

You will also want to consider the organization of your texts. The TEI provides many elements for encoding each document’s organization—the whole text goes in the <text> element; you have <front>, <body>, and <back> for the front matter, body of the text, and back matter; you have <div> for major textual divisions, and you have <p> for paragraphs and <ab> for paragraph-sized chunks of text that aren’t actually paragraphs.

Questions to consider:

  • What values do you want to use for @type on <div>? See an example list here.
  • Are there other aspects of the organization you want to specify? For example, if you have poetry, you might also want to use @type with <lg> (line group) to distinguish sonnets from limericks.

Rendition and Forme Work

As a project, you’ll want to consider what kinds of rendition you are interested in. “Rendition” describes the appearances of a text, and might include information on typography, alignment, ornamentation, use of decorative initial capitals, etc. You’ll want to specify any aspects of the rendition you have decided not to record and be able to articulate how you made such decisions. For example, it’s likely that you will consider the presence of italicized type significant no matter what approaches your project takes. However, levels of indentation might feel out of scope for the work you’re doing. Since encoding is a process of controlled information loss, most projects have to decide which features are not relevant for their work (and the research done by their users) or are simply too expensive (in time, and, often, actual money) to record. For example, the WWP devotes a fair amount of time to recording renditional details (see the rendition section of the internal documentation to get a sense of how much time), but the project nonetheless does not record some things—changes in font size, for example. So, think about which aspects of the rendition are important to you and decide how you want to encode them. As a group decide which aspects of your documents’ appearance you will not be encoding and record those decisions in your documentation. For an example, see the WWP’s statement on regularization. You will also want to consider what kinds of “forme work” you are interested in and how you’ll standardize the encoding of these features. Forme work includes page numbers, catchwords, signature marks, etc. See the TEI’s explanation of the <fw> element for more information. There might be some aspects of the forme work you will choose not to record, just as with rendition. Document these decisions as well.

Interpretation and analysis

As a project, you will also want to decide what kinds of interpretation and analysis you’d like to encode. To create a list of interpretive classifications, follow the example here. To this taxonomy of interpretive concepts with a particular element use the @ana attribute—if you want to apply analysis to a segment of text that is not already within an element, use <seg>. For example: Sample encoding: analysis You can define each <interp> in your documents (in an “editorial” <div> in the <back>), but you’ll also want to include a list of these in your documentation, and you might choose to expand on these and add examples there.