The Relationship between Documentation and the ODD File

Disambiguation

This documentation page is designed for documenters and does not explain the processing that includes documentation in the ODD file. For developers looking for documentation on code files and processing relevant to documentation, see <ref target="learn_odd_file_doc_guide.xml">Documentation and the ODD File</ref>.

Rationale

Unlike our XML files for editions and anthology About pages which are rooted on the TEI element, our documentation files are rooted on the div element. We root documentation pages on div because the content from each documentation file is compiled into one page via processing instructions in the ODD file. Processing documentation in this way allows us to display all of the contents of a single documentation chapter on one HTML page on our rendered website, which some people find useful when searching for specific content in a chapter.

The Documentation Index

All of our documentation files are compiled in one place in the documentation index. Our readers see the documentation index as the the HTML documentation landing page on our rendered website. As documenters, we also get to see the documentation index in the LEMDO ODD file (data/sch/lemdo.odd).

Our documentation is the content that makes up the body element of the ODD file; our schema specification lives in the back element.

In the body of the ODD file, each documentation chapter gets a div with a unique xml:id. Each div contains a head element which contains the chapter number and title that appear in the rendered documentation index. The documentation pages in each chapter are added using inline processing instructions that link to the individual documentation files. Prior to the processing instructions, chapters that are not yet completed and published have a single p element that contains the following sentence: This chapter of our documentation is still in beta. We welcome feedback, corrections, and questions while we finalize the page in our 2024–2025 work cycle. Once each chapter is completed, a member of the LEMDO team must remove the draft paragraph from the div for the chapter.

Note that the draft paragraph is not visible from the online documentation index page. It is only visible from the full chapter view that people can reach by clicking on the title for each chapter.

Processing Instructions

LEMDO’s developers have written a processing instruction to include documentation pages in our documentation index. For each documentation file that you wish to include in a documentation chapter, you must add a lemdo-include processing instruction. Doing so will add the documentation page to the next build and add a link to the documentation page from the documentation index. To add the processing instruction: Copy this instruction into the text node of the div for the chapter that you wish to add it to in the ODD file, placing it in the position in the chapter that you want it to be in: <?lemdo-include href="doc:[documentation xml:id]"?>. Replace [documentation xml:id] with the xml:id for the documentation file that you wish to add.

For more information on the lemdo-include processing instruction, see <ref target="learn_progProcessingInstructions.xml#learn_progProcessingInstructions_lemdo-include">lemdo-include</ref>.

Giving Credit in Documentation

Rooting documentation files on the div element means that documentation pages are unique in the LEMDO XML ecosystem in how we give credit to those who worked on files. While in most TEI files we give credit to contributors in respStmt elements in the titleStmt of the teiHeader, we are unable to do so in each documentation file as there is no teiHeader. Instead, we list all contributors to LEMDO documentation in the teiHeader of the ODD file and link to the relevant contributors’ xml:ids from the root div element of each individual documentation file using the resp attribute.

Note that because the responsibility statements that are shown on the rendered Web pages for documentation come from the ODD file rather than the documentation file itself, the order of contributors shown online follows the order that contributors are listed in the ODD file. Despite this, we do link to the xml:ids of contributors in the order of their contributions from the root div element of each documentation file (i.e., primary author of the file first, subsequent authors after). Following this practice ensures our underlying XML truthfully captures the contributions of each person to the extent possible.

For more information on our practice for giving credit in documentation files, see <ref target="learn_docEncode_credit.xml">Give Credit for Documentation Files</ref>.

Structure of Responsibility Statements in the ODD File

Because our ODD file contains both our documentation and our schema specification, there are responsibility statements for both the entire LEMDO project and for the LEMDO Encoding Guidelines in the teiHeader of the ODD file. The respStmt elements giving credit for the entire project to the project director, project manager(s), and developers are listed first, followed by the respStmt elements for technical writers of documentation, documentation compilers, encoders, copyeditors, and finally proofreaders. Each group is separated by an XML comment.

In the section for technical writers, the order of respStmt elements (and thus the order that names are listed in on the Credits pane on rendered documentation pages) puts lead documenters and major contributors first (given in the order of Janelle Jenstad, Navarra Houldin, Mahayla Galliford, Laura Estill, Martin Holmes) followed by all of our contributing authors. Contributing authors are listed in alphabetical order by surname.

Names in all other sections are given in alphabetical order by surname.