Writing Guidelines

RIDE transforms submitted reviews into XML documents adhering to the TEI standard. You can submit your review in any common and accessible text format (for instance an Open Office, Libre Office, or Word Document). While writing your review, please observe the following rules on formatting and editing:

Structure of the review

  • Every review should include an abstract (one paragraph) in English. The abstract should not be an introduction to the review but rather a concise summary of its content and findings.
  • Format the title as heading 1 (the title of your review should usually be the name of the project you are reviewing – without the addition ‘review of…’ – but can also be formulated freely – see the existing issues for examples).
  • Structure the document using headings 2-3 (don’t use levels below 3). Second order headings will be used to generate a Table of Contents (ToC) in the HTML presentation of the review. If you decide against the use of headings, the review will start with the heading “Review” (e.g. https://ride.i-d-e.de/issues/issue-1/nietzschesource/). If you decide to use headings, please start right at the beginning of the review with a second level-heading (exceptionally, you can also start with a quote, see e.g. https://ride.i-d-e.de/issues/issue-5/beckettarchive/, or with a short introductory paragraph clarifying the status of the review, see e.g. https://ride.i-d-e.de/issues/issue-6/litteraturbanken-the-swedish-literature-bank/).
  • The minimum length of a paragraph is two (better three) sentences.
  • Every review must include a list of relevant references (see also section on “Bibliography” below).
  • Come up with a number of keywords that describe what aspects of the reviewed project you deal with in particular. These keywords will be used to tag your review (see existing tags as examples).

Proof reading

General aspects of formatting

  • Use a Unicode font.
  • You may use italics to highlight words or phrases.
  • You may not use text colors other than black.
  • You can use footnotes (they will be transformed into endnotes in the HTML presentation and the PDF version of the review).
  • You can include blockquotes, lists, tables, pictures, code examples, and links in your review. Please see the corresponding recommendations for their use below.
  • Footnotes, figure captions, code example captions, and references end with a full stop.
  • Please consider the Bibliography section below.

Quotations

  • For quotes, please use the quotation marks that are common in the language you write your review in.
  • Mark gaps in quotes with square brackets and three dots: […].
  • You can use blockquotes. Please do not add quotation marks to blockquotes. Indicate the source of the blockquote directly after it (see e.g. https://ride.i-d-e.de/issues/issue-10/alfred-escher-briefedition/#p12).

Lists

  • In your review, you can use lists with bullet points, numbers, or other kinds of labels for the list items.
  • Lists can have sublists.
  • Lists cannot have any caption or number identifying them.

Tables

  • You can include tables in your review, which can have a table heading and a first row with column headings.
  • Add a caption and a number identifying them.
  • Reference the table from the text (e.g. “see table 1”).

Pictures

RIDE welcomes pictures and especially screenshots of reviewed projects that help the reader to understand what the project is or is not doing. Screenshots serve a documentary function, making available to the reader the state of a certain aspect of the project under review. While editions are expected to change their appearance in the future, the review will remain stable.

  • If you want to include pictures in your review, please number them in the order they are supposed to appear in the review and name them as follows: picture-1.png, picture-2.png, etc.
  • We prefer pictures in the PNG format.
  • Please send your pictures as image files in a separate zip file.
  • Please make sure that the quality of your screenshots is appropriate for online publications.
  • Please insert the pictures into your review and add a number and a caption to every picture, eg. “Fig. 1: Caption.”
  • !important Due to the formatting in WordPress (the CMS we use to publish your review in HTML) it can happen that image and text are not always next to each other. Therefore every figure should be referenced from the text in the language of your review, e. g. “(see fig. 1 / siehe Abb. 1)” or “As fig. 1 shows…” / “Wie in Abb. 1 zu sehen, …”.

Code examples

We welcome code examples in your review. You can cite code either directly in the text or as blocks. Inline code citations can for example be mentions of XML elements or attributes (e.g. “Referring strings are encoded with the element <rs> and described further with @type.”). The use of blocks is recommended if the code examples are longer or have a more complex structure, for example:

<teiHeader>
  <fileDesc>
      <titleStmt>Digital Thoreau</titleStmt>
  </fileDesc>
</teiHeader>

Code 1: TEI Header.

if $title == “Review”:
    print(“this is probably a review”)
else:
    print(“this may be something else”)

Code 2: Condition for reviews.

In general:

  • Reference the code from the text (e.g. “see code 1”).
  • Inline code examples do not need to be highlighted with quotation marks, but we recommend to use an own font for them (e.g. Courier), which facilitates that we recognize them for the editing process (in the TEI of the review code examples are marked up).
  • Block code examples need to be enhanced by descriptive captions, e.g. “Code 1: Caption for this code example”.
  • Block code examples can also be referenced from the text (e.g. “see Code 1” / “siehe Code 1” / etc.); however, since they are embedded in the flow of paragraphs, they do not necessarily need to be pointed to.
  • In block code examples, line breaks are preserved and also whitespaces/tabs can be preserved, especially if they are significant for the code.
  • We do not support special font colors for displaying code.

Obviously, RIDE allows and encourages the use of links to other resources in the web (web pages, APIs, documents, files, etc.). In a review, links can serve a variety of functions, for example to point to specific sites that are discussed in the review or just be part of bibliographic references. Depending on what the links are about, we recommend different strategies. It is the aim of RIDE to keep reviews transparent and comprehensible even if the digital resources that are reviewed change over time. On the other hand reviews encoded in TEI and published in HTML should make use of the possibility to point to other web resources directly and in a dynamic way. These two goals are sometimes conflicting ones. To cover both aspects, we have some recommendations to give you some guidance and still leave room for your style of using links:

In general:

  • Please provide complete links including the protocol (http, https).
  • Links can be explicitly mentioned in the text, e.g. in order to name the landing page of the project under review or another one, but should not be spelled out in the text in other cases.
  • Links can be embedded in the text by linking words or passages of text to some other destination.
  • Links can also be given explicitly or be embedded in footnotes.
  • Explicit links can be part of bibliographic references.

Important:

  • If you cite links of the resource under review or other resources because you discuss the details of the corresponding website(s) – e.g. their content, structure, design, etc. – , they should be archived (see instructions on how to archive links below). You can embed archived links in the text like this or include them in footnotes or references. Archiving such links makes sure that the discussion of the resource in your review can be followed even if the web addresses of the resource have changed or do no longer exist. This happens more often than you might expect! – for example when a resource is updated technically, relaunched, moved, or abandoned for some reason.
  • Exceptions to the previous recommendation are pages that have their own DOI or a permalink for which it can be assumed that they will be permanently accessible. However, please note that even a general DOI can point to a site with changing content or comprise a whole set of sites which can change.
  • If you cite links as part of bibliographic references or just as general references to other resources, sites, or projects (e.g. “an example of a free encyclopedia is Wikipedia”), you do not need to archive them. In case you embed such links in the text, just leave them as they are. If you use them in footnotes or references, we recommend adding the date when you accessed the links, in the form ‘Accessed: Date’ (see the Bibliography section below for details). If you accessed all those links on the same day, you can also indicate a general accessed-date in a footnote at the beginning of your review (e.g. “All links accessed on …”) – please observe that sites that you discuss should still be archived!

How to archive links:

To archive links, please use the archive.org ‘Save Page Now’-service. With this, a snapshot of a page can be created which is versioned and persists over time. In order to create a snapshot, navigate to http://archive.org/web/ and enter the link in the ‘Save a Page’ form. This will create a snapshot and refer you to the saved page. Please use the link of this saved page instead of the original link in your written review. For archived links, no “Accessed”-date, which is usually required in the bibliographic accounting of web-links, needs to be indicated. Example:

Original link: http://www.pessoadigital.pt/en/index.html

Snapshot link: https://web.archive.org/web/20210228175136/http://www.pessoadigital.pt/en/index.html

Caveat: Unfortunately, not every page is archivable using the ‘Save a Page’ service. Some server configurations are incompatible with the service and sometimes the application itself will make it impossible to refer to a specific page. Please always check whether the snapshot really contains the data you try to archive. Should you be unable to create a usable snapshot, revert to the ‘Accessed: Date’ method outlined below in the section on bibliography or include a screenshot if appropriate.

Bibliography

RIDE reviews require the provision of a bibliography. RIDE uses the Chicago Author-Date style. A short summary can be found here.

Some examples for in-text citations:

  • Direct citation with page: These notes and scribbles are commonly referred to as ‘marginalia’ and are the first traces of what John Bryant calls ‘the moment of artistic creation’ (Bryant 1991, 5).
  • Direct citation, several authors, without page: But for the autodidact Herman Melville reading served as “the means and impetus for his phenomenal literary achievements” (Olsen-Smith, Norberg, and Marnon 2008).
  • Indirect citation, two references with pages: It was considered a useful reading aid that allowed the reader a better comprehension of a given text (Hooks 2012, 636; Blair 2003, 11).

Some examples for entries in the bibliography:

  • Book: Cowen, Wilson Walker. 1987. Melville’s Marginalia. New York: Garland.
  • Chapter in an edited book: Hooks, Adam G. 2012. “Marginalia.” In The Encyclopedia of English Renaissance Literature, edited by Garret A. Sullivan, Jr. and Alan Stewart, 636-637. London: Wiley-Blackwell.
  • Journal Article: Bryant, John. 1991. “Melville’s ‘Typee’ Manuscript and the Limits of Historicism.” Modern Language Studies, 21 (2): 3–10.
  • Website (archived, subpage): Olsen-Smith, Steven, Peter Norberg, and Dennis C. Marnon. 2008. “Online Catalog of Books and Documents Owned, Borrowed and Consulted by Herman Melville.” Melville’s Marginalia Online. http://web.archive.org/web/20140805084911/http://melvillesmarginalia.org/m.php?p=userinterface_new. 
  • Website (accessed-date, whole website): Sepúlveda, Pedro, Ulrike Henny-Krahmer, and Jorge Uribe, eds. 2017. Digital Edition of Fernando Pessoa. Projects and Publications. Accessed February 28, 2021. http://www.pessoadigital.pt/en/index.html. 

For further examples please consult external documentation of the Chicago-Author-Date style.