LEMDO: Documentation Style Guidelines

Documentation Style Guidelines

¶ Writing

Consult this style guide for rules specific to documentation, otherwise, follow the LEMDO Style Guidelines.

¶ Voice and Pronouns

Keep voice, diction, pronouns, and other elements of language consistent across the documentation. Always write in the active voice.

Use imperative second-person verbs at the beginning of headings whenever possible (e.g. Create a New File).

Write documentation in first-person plural (we, our) to describe what we did in a particular case or what we do on the project in general; the verb tense can be past or present depending on what we are describing.

Use second person (you) and imperative verbs when giving instructions to contributors and team members.

For third-person pronouns, do not use gendered pronouns unless you are referring to a specific person and you know the person’s preferred pronouns. Otherwise, use the gender-neutral singular pronoun they or phrase the entire sentence in the plural. Do not use he/she or s/he, which, in addition to being awkward, reinforce an outdated binary notion of gender.

¶ Standard Diction for Headings

Use LEMDO’s standard diction to help readers understand the purpose of each section of a documentation file. Users will quickly begin to understand how the documentation is organized if we use these terms consistently. If all a user needs is a refresher on the steps, they will know to look for the section with the term Step-by-Step. These are the terms we use:

Rationale sections explain why we follow the encoding practice being described in a particular documentation file.

Principles sections outline the project principles that we follow when developing encoding practices. Principles give us a set of rules by which to make encoding decisions in cases where we cannot outline every possible use case or example.

Practice sections explain specific encoding practices and often include both prose and lists.

Workflow sections are usually lists and outline the steps required to complete a particular encoding project and the order in which users typically undertake those tasks.

Step-by-Step sections are numbered lists designed to be skimmed quickly with short instructions on how to complete a certain encoding task.

At a Glance sections often include tables with just the information the user is most likely to need, such a quick visual of the pattern for making xml:ids.

Examples sections include examples of the encoding described in the documentation file.

Special Cases sections include examples that are atypical but still appear in encoding and must be taken into account.

Tips sections include non-essential but helpful information, such as strategies that allow users to work more efficiently.

Optional sections include encoding practices that are not relevant to some users or in specific scenarios.

Rendering Note sections give information on how the encoded material will look on the LEMDO site or how the encoding practice will affect rendering.

Disambiguation sections distinguish between similar things that users may assume are the same. They usually include links to other documentation pages with information on the thing being disambiguated.

Prior Reading sections include links to documentation pages that should be read before reading the current page.

Further Reading sections include links to documentation pages that should be read after reading the current page.

Use these terms in the


                                             <head>

elements of documentation


                                             <div>

elements and wherever it seems appropriate to repeat the terms in the running text.

If you need to write two sets of instructions of varying complexity, use the headings Step-by-Step: Basic and Step-by-Step: Advanced. If you are only writing one set of instructions, use the heading Step-by-Step.

¶ Diction in Running Text

Use plain language in your writing. Link to GLOSS1 if users require knowledge of technical terms and provide an explanation of concepts that require specialist knowledge to understand your documentation.

Consider your audience and try to judge their familiarity with technical terms. On one hand, you may use editorial terminology in the editorial guidelines because the audience for that documentation are editors who will be comfortable with it. On the other hand, do not use programming jargon in an encoding Quickstart guide unless you provide explanations that are accessible to the audience of beginner encoders.

Modal verbs have particular meanings in the world of documentation. RFC 2119 (1997) sets out rules for the use of must, must not, required, shall, shall not, should, should not, recommended, may, and optional in documentation. The TEI Guidelines, which we quote from and link to in our guidelines, use a subset of these modal verbs. RFC 2119, point 6 argues against the use of imperatives. However, we are writing documentation primarily for editors, encoders, and LEMDO team members, most of whom need clear, simple instructions. We tend to write our documentation in the imperative second-person, mainly to avoid repeating the implied modal verb must. If something is truly optional or recommended, say so.

Consider audience when writing headings in documentation files. Editors are more likely to go to documentation looking for the solution to an editorial problem, not looking for a description of an encoding protocol. Write headings like Encode Element Names instead of headings like Use


                                                <gi>

. Remember that the text nodes of


                                             <head>

elements will be generated into a table of contents later, and write headings that will direct readers to the solution they need.

Use consistent language across the documentation. Occasionally we will recommend wording for phrases or sentences that will be used often across our documentation.

We anticipate that readers will go to certain pages looking for information that is actually on another page. You may also want to direct a reader to a more in-depth explanation of a concept. Always link to the page that you mention. Choose a phrase from the list below to recommend further reading to users:

If you are looking for information on encoding foreign languages, go to <ptr target="doc:learn_encodeForeignLanguages"/>.

See also <ptr target="doc:learn_encodeForeignLanguages"/>.

Be clear when you are talking about specific elements, attributes, and values. Note that when you are encoding elements, attributes, and values, you will wrap them in the elements


                                             <gi>


                                             <att>

, and


                                             <val>

, but you also want to add clarifying words (see Encode Sample XML for encoding instructions):

Add the word element after the name of the element so it is clear that you are referring to the element. Example:

“LEMDO uses the


                                                         <title>

element to tag the titles of written works”

Add the word attribute after the @name of the attribute. Example:

“Add a


                                                      @ref

attribute to the


                                                         <name>

element.”

Add the word value before or after the name of the value. Examples:

“Give the


                                                      @corresp

attribute the value of the xml:id in the BIBL1 file.”

“If the stage direction describes an action, add the "action" value to the


                                                      @type

attribute on the


                                                         <stage>

element.”

¶ Spelling

Write Quickstart (e.g., Quickstart guide), not Quick start, QuickStart, or Quick-start.

Write ODD file in full capital letters, but write .odd when referring to the file extension.

Write Web page with Web capitalized and page not capitalized. Write Web site the same way.

Write website when you are referring to the final output that has a URL.

Write file name, not filename.

Write checkout, not check out when using the noun form.

Write screenshot, not screen shot, or screen-shot.

Write hash character, not hashtag, when referring to the following character: #.

When using born digital as a phrasal adjective (e.g., in the phrase born-digital text), write born-digital text, not born digital text.

Write work session as two words, not as a single word.

Write tagset, not tag set.

Write workflow, not work flow.

Write sitewide, not site-wide.

When referring to hungwords, write turnover, not turn-over. Also write turnunder, not turn-under

Write forme work, not formework.

Write markup, not mark up or mark-up when you are referring to markup as a noun. Reserve mark up for the action of adding markup.

Write A.S.Sp., not A.S.SP when referring to our system of canonical references.

Write multivolume, not multi-volume.

Write shelfmark, not shelf-mark

In titles and headings, capitalize both elements in hyphenated words, unless the first element cannot stand alone as a word (e.g., anti-). For example, write Previously-Encoded and Anti-climactic, not Previously-encoded and Anti-Climactic. The exception is Semi-Diplomatic, in which both elements should be hyphenated.

¶ Punctuation

Avoid semicolons in documentation.

Do not use two hyphens or two en dashes in place of an em dash ( — ) in documentation. You can insert an em dash using LEMDOʼs list of special characters. See Practice: Bring Up a List of Special Characters.

Use a period at the end of each item in a list unless every item in the list is a link with no other text.

¶ Capitalization

Write xml:id in lowercase, not in partial or full capital letters (i.e. not XML:id or XML:ID), but write XML in capital letters when referring to the encoding language.

Write ID (e.g., NetLink ID), not id or Id, when not referring to xml:id.

Write Oxygen, not oXygen when referring to the encoding software we use (the company that makes Oxygen uses both spellings).

Write TEI P5 without a hyphen.

Write affiliate identity, not Affiliate Identity.

Capitalize Schematron.

Capitalize Subversion and SVN.

Capitalize Terminal.

Capitalize Quickstart.

Write regex in lowercase.

Write NetLink, not Netlink or netlink.

¶ Application Instructions

Use a Unicode arrow (U+2192) from the character map (i.e., →) to illustrate how to find things in the menus of computer applications (e.g., Word, Teams, Oxygen).

Example showing a Unicode arrow used to give instructions:

Click Project → Open Project → lemdo-all.xpr.

¶ Organization

Plan out the structure of your documentation before writing and encoding it. Consider the users of the documentation and what they will expect from it. Encoding documentation also becomes easier if you have a structure in mind beforehand.

Use point-first writing at the sentence, paragraph, and page level. Briefly outline what you will be talking about at the beginning so users can quickly decide whether it is relevant to them or not.

Order the options from most likely/advisable to least likely/advisable when we have several possible encoding scenarios and solutions. Some scenarios are ubiquitous across early modern drama, but given the type of material we edit and encode at LEMDO, others are infrequent. However, we still have to imagine an encoding solution for the infrequent scenarios.

Guide the encoder or editor by putting the most common scenario first. For example, LEMDO uses several different elements to tag quoted and highlighted text. The element with the least-specific use,

<q>

, is at the bottom of the list in the documentation for quotation elements because we only want users to choose that element after they have tried all of the more specific elements. The element that users will most likely need,


                                          <quote>

, is at the top of the list.

Use


                                          <div>


                                          <head>

, and


                                          <list>

elements whenever possible to make documentation easier to read and scan. However, do not use


                                          <list>

unless the material really is a list. Break up long blocks of text whenever possible.

¶ Cite the TEI Guidelines

Name and link directly to relevant sections of TEI P5. Simply citing the TEI Guidelines with parenthetical references and links to BIBL1 is not specific enough for our purposes.

Note that anything tagged with


                                          <gi>

will be automatically processed into a link to the relevant LEMDO element specification, which in turn links to the element specification in the TEI Guidelines.

Treat the TEI Guidelines as a monograph and make a direct link to them. Encode TEI Guidelines with the


                                          <title>

element, the


                                       @level

attribute and the value "m".

Treat chapters of the TEI Guidelines as articles and make direct links to them. Encode the names chapters with the


                                          <title>

element, the


                                       @level

attribute and the value "a":

See also <title level="a">Chapter 16: Linking, Segmentation, and Alignment</title> in the <title level="m">TEI Guidelines</title>.

Prosopography

Isabella Seales

Isabella Seales is a fourth year undergraduate completing her Bachelor of Arts in English at the University of Victoria. She has a special interest in Renaissance and Metaphysical Literature. She is assisting Dr. Jenstad with the MoEML Mayoral Shows anthology as part of the Undergraduate Student Research Award program.

Janelle Jenstad

Janelle Jenstad is a Professor of English at the University of Victoria, Director of The Map of Early Modern London, and Director of Linked Early Modern Drama Online. With Jennifer Roberts-Smith and Mark Kaethler, she co-edited Shakespeare’s Language in Digital Media: Old Words, New Tools (Routledge). She has edited John Stow’s A Survey of London (1598 text) for MoEML and is currently editing The Merchant of Venice (with Stephen Wittek) and Heywood’s 2 If You Know Not Me You Know Nobody for DRE. Her articles have appeared in Digital Humanities Quarterly, Elizabethan Theatre, Early Modern Literary Studies, Shakespeare Bulletin, Renaissance and Reformation, and The Journal of Medieval and Early Modern Studies. She contributed chapters to Approaches to Teaching Othello (MLA); Teaching Early Modern Literature from the Archives (MLA); Institutional Culture in Early Modern England (Brill); Shakespeare, Language, and the Stage (Arden); Performing Maternity in Early Modern England (Ashgate); New Directions in the Geohumanities (Routledge); Early Modern Studies and the Digital Turn (Iter); Placing Names: Enriching and Integrating Gazetteers (Indiana); Making Things and Drawing Boundaries (Minnesota); Rethinking Shakespeare Source Study: Audiences, Authors, and Digital Technologies (Routledge); and Civic Performance: Pageantry and Entertainments in Early Modern London (Routledge). For more details, see janellejenstad.com.

Joey Takeda

Joey Takeda is LEMDO’s Consulting Programmer and Designer, a role he assumed in 2020 after three years as the Lead Developer on LEMDO.

Martin Holmes

Martin Holmes has worked as a developer in the UVicʼs Humanities Computing and Media Centre for over two decades, and has been involved with dozens of Digital Humanities projects. He has served on the TEI Technical Council and as Managing Editor of the Journal of the TEI. He took over from Joey Takeda as lead developer on LEMDO in 2020. He is a collaborator on the SSHRC Partnership Grant led by Janelle Jenstad.

Navarra Houldin

Project manager 2022–present. Textual remediator 2021–present. Navarra Houldin (they/them) completed their BA in History and Spanish at the University of Victoria in 2022. During their degree, they worked as a teaching assistant with the University of Victoriaʼs Department of Hispanic and Italian Studies. Their primary research was on gender and sexuality in early modern Europe and Latin America.

Nicole Vatcher

Technical Documentation Writer, 2020–2022. Nicole Vatcher completed her BA (Hons.) in English at the University of Victoria in 2021. Her primary research focus was womenʼs writing in the modernist period.

Tracey El Hajj

Junior Programmer 2019–2020. Research Associate 2020–2021. Tracey received her PhD from the Department of English at the University of Victoria in the field of Science and Technology Studies. Her research focuses on the algorhythmics of networked communications. She was a 2019–2020 President’s Fellow in Research-Enriched Teaching at UVic, where she taught an advanced course on Artificial Intelligence and Everyday Life. Tracey was also a member of the Map of Early Modern London team, between 2018 and 2021. Between 2020 and 2021, she was a fellow in residence at the Praxis Studio for Comparative Media Studies, where she investigated the relationships between artificial intelligence, creativity, health, and justice. As of July 2021, Tracey has moved into the alt-ac world for a term position, while also teaching in the English Department at the University of Victoria.

Bibliography

TEI Consortium, The. TEI P5: Guidelines for Electronic Text Encoding and Interchange. Ed. C.M. Sperberg-McQueen and Lou Burnard. Revised and expanded under the supervision of the Technical Council of the TEI Consortium. Text Encoding Initiative Consortium, 2020. https://tei-c.org/release/doc/tei-p5-doc/en/html/index.html.

Orgography

LEMDO Team (LEMD1)

The LEMDO Team is based at the University of Victoria and normally comprises the project director, the lead developer, project manager, junior developers(s), remediators, encoders, and remediating editors.

Metadata

Authority title	Documentation Style Guidelines
Type of text	Documentation
Short title
Publisher	University of Victoria on the Linked Early Modern Drama Online Platform
Series	Linked Early Modern Drama Online
Source	TEI Customization created by Martin Holmes, Joey Takeda, and Janelle Jenstad; documentation written by members of the LEMDO Team
Editorial declaration	n/a
Edition	Released with Linked Early Modern Drama Online 1.0
Encoding description	Encoded in TEI P5 according to the LEMDO Customization and Encoding Guidelines
Document status	prgGenerated
Funder(s)	Social Sciences and Humanities Research Council of Canada
License/availability	This file is licensed under a CC BY-NC_ND 4.0 license, which means that it is freely downloadable without permission under the following conditions: (1) credit must be given to the author and LEMDO in any subsequent use of the files and/or data; (2) the content cannot be adapted or repurposed (except in quotations for the purposes of academic review and citation); and (3) commercial uses are not permitted without the knowledge and consent of the editor and LEMDO. This license allows for pedagogical use of the documentation in the classroom.