Skip to content

3.3 Documentation

The purpose of DSE documentation is not only to provide general, philological, and technical information for users but also to enable and simplify the subsequent reuse of the DSE. For both users and future users, it should be clear how the edition data was created, who created it, when it was created, where it was created, and why it was created. The University Library of Zurich offers a useful overview of data reuse here.

DSE documentation is a central component of a DSE, which is why the time of its creation should be recorded in the project plan, along with the documentation responsibilities within the project team, starting in the planning phase. If possible, one person should take primary responsibility for the documentation, gathering the individual aspects (see below) from the relevant specialists. During the planning phase, it should also be determined how detailed and in which data format the documentation needs to be (see below), as the documentation ideally occurs during the work processes themselves, requiring only minimal editorial revision at the end.

In the following sections, we refer in detail to the Documentation of the Showcase Edition, which reiterates many of the explanations in this manual (particularly the editorial guidelines regarding transcription, annotation, and commentary).

It should be noted that standardized documentation structures or terms for documentation aspects have only been partially established to date; this sometimes makes it difficult to compare different documentation practices. While standardization would be desirable, this chapter is not intended as a proposal for such a standard, but rather as an attempt to conceptualize documentation in terms of (necessary and desirable) requirements.

What Does DSE Documentation Contain?

DSE documentation replaces the editorial commentary of a printed edition (which typically provides a brief explanation of the basics of text constitution and editorial guidelines) or its editorial afterword (which additionally explains the historical background of the edition and philological aspects).

The edition model of DSE documentation complements these traditional editorial explanations with its guidelines for the creation of text-critical and content-related annotations and comments in TEI/XML. In other words, it clarifies which coding is used for different forms of annotation and commentary in TEI/XML. The DSE is therefore documented not only as an edition (philologically) but also as a code (technically), with these two aspects being inseparably intertwined. => Edition model of the showcase edition

Thus, the DSE documentation also encompasses digital aspects that have no equivalent in print, such as:

Accessibility and Presentation

Depending on the size, complexity, and innovative content of a DSE, different requirements may need to be met by DSE documentation, but it should fulfil certain basic requirements in its presentation: It should be recognizable as documentation and provided alongside the list of edited texts, the index, or the search functions.

We generally recommend clearly separating the categories of documentation into technical, philological, and organizational topics. General information on the project structure can also be presented outside the documentation (e.g., as a project entry page about the institutions, team, or funding involved). Background information on the edited content is generally not part of the documentation (such as scientific supplements in the form of overview comments). Citation suggestions can be included in the documentation, but the minimum requirement is, as already mentioned, to provide a clearly visible citation suggestion for each distinct page. It should not be necessary to consult the documentation in order to cite a DSE.

Documentation Types

The minimum requirement for documentation is a brief, keyword-like explanation of all visible/usable components of the DSE, which corresponds more to the editorial commentary in a printed edition. The various aspects can be separated into simple sub-chapters and combined on a single page, making it easy to generate a PDF. This may be sufficient for a smaller or less complex DSE, especially if it continues a previous practice. In this case, it is advisable to refer to the exemplary DSEs in your own documentation.

Example DSE: Minimal Documentation

The Digital Edition of the Travel Diaries of Johann Conrad Fischer 1794–1851 is a visually appealing DSE of a printed corpus that has already been critically edited in book form, now primarily utilizing the advantages of simple linking and visual enrichment. Since it is based on established functions of the TEI Publisher, the documentation only provides minimal details about Edition history and technology and the Edition guidelines.

In contrast, an extensive documentation has more of the character of an editorial afterword and is divided into several subpages for better clarity. The more a DSE project is intended to serve as a role model within a community and/or the more innovative a DSE project is, the more detailed the documentation should be.

Example DSE: Detailed Documentation

Two DSEs are presented below that are 'haute couture' editions in technical terms and feature correspondingly detailed documentation.

The DSE Der Sturm brings together and edits a wide variety of very different documents related to the international avant-garde of the 20th century. This requires various complex editorial guidelines, etc. It features detailed and clearly structured documentation of its digital methodology, its TEI/XML coding and its data resources (including an interface for accessing its own data).

The previously mentioned letter correspondence DSE hallernet is one of the most ambitious projects of recent years in terms of its database. This is also reflected in its documentation. A separate subdomain, almost exclusively in English, was created for this, which contains three main categories (Guidelines/System/Usage) with subchapters. Particular attention is paid to the data model of the metadata. The documentation is primarily aimed at a technically and philologically sophisticated audience.

Tools and Data Formats

Use of TEI/XML

DSEs can write their documentation in the same data format, usually TEI/XML, as the edited text. This is useful if the documentation is to be published with the same tool, such as TEI Publisher. However, it should be noted that TEI/XML is a more complex data format than is typically required for documentation and, unlike Markdown (see below), it is not a fixed standard but offers more flexibility. This is particularly relevant when parts of the documentation are written by employees who are not involved in the editing process (e.g., technical staff responsible for the front end or long-term preservation) and would, therefore, need to familiarize themselves with TEI/XML solely for this purpose (or their files would need to be converted).

Conclusion: In small teams familiar with TEI/XML, the TEI/XML data format and associated tools are a good choice. An alternative simplified XML format, used in TEI Publisher documentation, for instance, is DocBook XML.

Use of Markdown, e.g., with MKDocs or VitePress

Markdown is a data standard for technical documentation and, therefore, provides sufficient functionality for DSE documentation. Additionally, there are several freely accessible Python libraries that allow more complex documentation to be created with relatively simple tools. One such Python library, MkDocs, was used for this manual.

The documentation of hallernet (see above) is Markdown-based and is automatically generated in a CI workflow using a common tool for creating documentation (VitePress).

Markdown files can ultimately be published in various ways. For projects that use the TEI Publisher, it may be useful to publish their Markdown files directly in the Publisher, as explained in more detail in the TEI Publisher documentation.

Archiving of Documentation

In the context of the overall archiving of DSE in repositories, the documentation can also be stored as a separate file (e.g., PDF), such as here in SWISSUbase.