Do not duplicate information across our documentation. Document and prescribe practices in the files that will be the most useful to the greatest number of users.

Check all locations where we keep documentation to make sure that the documentation has not already been written. Do a keyword search in all the locations. At the time these Documentation Guidelines are being written (2020), we have documentation in the repository (…/data/documentation) and in Microsoft Teams.

Decide where your file will fit into the rest of LEMDO’s documentation. Without this information, developers will not be able to process your documentation file. Consider whether the documentation you are writing should be a standalone section or if it could be added to an existing section. Talk to a developer about your documentation files if you think they should be in an entirely new section. See LEMDO’s Documentation Index for a bird’s-eye view of the documentation chapters and sections. See General Documentation Structure for information on how to add your new section to the Documentation Index.

Do not overwhelm users with information they don’t need about highly specialized editorial or encoding challenges. From the main documents, point to other documents with more specific information, solutions to unusual problems, and special cases. Point back to the general documentation from this more specialized documentation, in case users needing more general information land in specialized documentation through a search.

The exception to the rule about general and specific documentation is documentation for remediators. Remediation is a specialized activity that presupposes a good knowledge of our editorial and encoding procedures; our remediators are generally not editors, however, and tend to learn encoding by remediating. So our documentation for remediators has to point back to the more general information. However, we do not want to point from the general documentation to the remediation documentation, which regular users of the LEMDO guidelines will not need.

For example, you will want to create one piece of documentation explaining how to create a bibliography (for editors) and one explaining how to remediate a bibliography (for remediator-encoders). You will want to link from the latter to the former, but not from the former to the latter.

All sample XML tagged with <egXML> needs to be clearly flagged as valid or invalid, using the @valid attribute and the values of "true" or "false". Create valid examples as much as possible so that editors and encoders can copy the sample XML into their own files as a template. We check the validity of all examples tagged with <egXML> and given the value "true". Checking the validity of supposedly valid examples means that we are prompted to update our examples if the schema changes. That means that valid examples must be wrapped in their parent element to be valid and contain all of the child elements required to complete the parent element. When this principle conflicts with the principle of Economy of Example, use your judgement to decide whether validity or economy is most helpful to the editor or encoder. (Note that LEMDO does not use the "feasible" value on the @valid attribute, even though it is an allowed value in the tei-all schema. Our constrained schema disallows "feasible". See Encode egXMLs.)

Remove any tags from sample XML that are not relevant to the example, with the caveat that the sample XML should still aim to be valid as often as possible. If the example becomes unnecessarily complex in the service of achieving validity, then consider offering a bare-bones example and giving the @valid attribute the value of "false". If the value is "false", we will be able to add a note or flag at rendering time noting that the example is incomplete and will require additional elements to be complete and valid. When this principle conflicts with the principle of Validity of Example, use your judgement to decide whether validity or economy is most helpful to the editor or encoder.

Each page must stand alone, even though we have structured the documentation as a book with chapters and sections. There is no guarantee that a user will have read an earlier page, and the generous linking within our documentation means that a user may have directed to a page from a variety of other pages. Furthermore, users may stumble across a page via a search of either the site or of the internet. Landing in the middle of a book is disorienting. Try to direct readers back to general pages. If a page presupposes knowledge, be explicit that the instructions assume knowledge of X, Y, and Z (and point to those pages or chapters).

We use TEI-XML across the project so that documentation can be processed in the same way as other born-digital files. This principle means that the most meta aspects of our documentation need to be presented as images (for example, documentation on how to encode examples in documentation, a problem which even the TEI Guidelines have not resolved well).