Requirements Documentation

By Shane A. McGarry

Introduction

Purpose

The purpose of this document is to describe the requirements for the Digital Scholarly Edition of the Albert Woodman Diary. This document is meant to describe in full all the required features that will be submitted with the digital edition upon its initial completion at the end of the Spring 2015 Term at Maynooth University.

Background

The Albert Woodman Diary was a diary kept by Albert Woodman (1891–1969) from January of 1918 until November of 1918. The diary details his thoughts and experiences during his service in the Royal Engineers ‘L’ Signal company as a signaler. The diary comes to Maynooth University via Albert Woodman’s granddaughter, Joyce Timms. Joyce provided the original diary, along with transcriptions of each page. The diary was subsequently scanned, and the images turned over to the 2014–2015 Digital Scholarly Editing module (AFF606A) at Maynooth University.

As part of their course requirement, the students of AFF606A have been tasked with creating a digital edition of the diary. Overseen by Professor Susan Schreibman, the students were given freedom to design the overall interaction and branding of the edition, as well as the choice of technologies to use in its implementation. The students were also tasked with encoding the diary in TEI, and decided to leverage XSLT to convert the encoded documents into XHTML.

Intended Audience

This document is intended to be read by members of the Albert Woodman Diary project team, as well as by Professor Susan Schreibman. Additionally, this document is intended for consumption by any parties interested in the development of the digital edition.

Scope

The scope of this document is to describe the detailed workflow and functional requirements as they relate to the Albert Woodman Diary digital edition and any of its requisite components. It is not intended to describe changes to any existing software beyond what is specifically described within this document nor is it meant to dictate system interactions beyond what is explicitly defined herein.

Overall Description

Software Audience

This digital edition is targeted to the general public. Due to the generalised nature of the source material, no particular specialised audience has been targeted. As such, interactions and requirements will remain generalised.

Operating Environment

The digital edition will be hosted by Maynooth University’s Computer Centre. It will reside on a Linux server utilising a standard LAMP stack. Due to budgetary constraints, open source technologies will be leveraged whenever possible.

Risks

Risk Severity (HML) Likelihood (HML) Contingency
Software Implementation H M Leverage Shane / Richard for coding needs
Scope Creep H H Try to keep a tight reign on features. Regularly report on status and compare to timeline(s).
Scheduling Issues L L Coordinate via Skype when necessary. Leverage Jira to track tasks and keep up to date.

Constraints

The primary constraints of the project are time and resources. The project must be completed by the end of the Spring Semester (mid-May) in order to give the MA students adequate time to complete their theses. Additionally, the project has limited technical resources as most project team members are not programmers by trade.

Assumptions & Dependencies

  • It is assumed the team will leverage existing software packages wherever possible so as to mitigate the amount of coding work necessary to implement the diary.
  • It is assumed the diary website will be hosted by Maynooth University and all requisite servers will receive standard support.
  • It is assumed the diary website will remain relatively static once it is launched and will not require regular code maintenance upon its final implementation.

Features

View Diary Entry

The primary feature of the digital edition is the ability to view an entry of the diary. This requirement should contain the following features:

  • View the transcription of the diary entry
  • View the image of the diary entry
  • View the image and the transcription side by side
  • Zoom in and out on the image
  • See information regarding annotations
  • See information regarding named entities
  • Right click / save image disabled
  • Navigate forwards and backwards (next and previous entries)

Simple View

In addition to the standard view described above, a more simplistic view of the diary should be provided. This view should allow the user to read the diary in a single, scrolling page view, allowing it to be consumed en masse without the need to navigate between entries. As this is a simple view, this view will not contain any of the additional features of the standard view, such as:

  • Viewing the entry with the image
  • Navigation to other entries
  • Citations (as described in Citations section)
  • Related Media (as described in Related Media section)
  • Editorial Notes (as described in Editorial Notes section)

The goal of this view is to provide a simple reading interface. However, each entry should provide a hyperlink to the standard reading view for that entry so that the user can jump to the more nuanced approach described in View Diary Entry. However, this link is one-way and the standard view will not provide a link to the simple view of a particular entry due to scope and time constraints.

Browse Diary

The diary should allow for the ability to browse. This should be represented in 2 ways:

  1. On the diary entry page (see View Diary Entry for further requirements), the user should be able to select a particular date from a calendar-like control. This date will then navigate the user to the appropriate HTML file for that date.
  2. An initial landing page for a “Browse Diary” menu option should display an interface that will allow the user to choose a date from which to begin browsing the diary.

NOTE: Due to time and technical constraints, only the ability to browse by date will be supported. The diary will not support the ability to browse by other metadata points, nor will it support a free-text search feature at this time.

Citations

The diary should also contain a “How to cite this entry” feature. If the user selects this functionality, they should be presented with the ability to select one of the following styles:

  • MLA
  • APA
  • Harvard
  • Chicago

Upon selection, the user should be presented with a citation containing information about the currently viewed entry in the format specified.

Related Media

In addition to the requirements laid out in the View Diary Entry section, each entry should have the ability to display related media. This media will be images that correspond to that particular entry (such as images taken of newspaper clippings that AW added to the diary). Both a thumbnail of the image and a full size version that allows for zoom should be displayed. NOTE: At this time, only images will be supported for related media. No other media formats will be considered for this initial phase due to time and technical constraints.

Editorial Notes

Each entry shall also allow for the display of editorial notes. Not all entries will have editorial notes, so if no notes are available on the entry, this section should preferably be hidden from view.

CMS Component

The diary entries will be wrapped by a CMS component that will allow for additional pages to be created. These pages will host content such as blogs, historical context regarding the diary, possible featured entries, information about the project as a whole, as well as other content to be determined by the team. The exact content to be created will be detailed in another document.

External Interfaces

WordPress

WordPress will be the CMS component leveraged for requirement CMS Component. As such, WordPress will need to be installed and configured on the server and will need to be customised accordingly to fit the requirements and branding of the digital edition.

XML

This digital edition will not utilise any underlying database. Rather, it will rely on XML files and the use of XSLT to produce XHTML to be rendered for each diary page. XSLT and the requisite processing will be developed by the project team.

Non-Functional Requirements

Performance

The diary is expected to be functional 24×7 with minimal downtime for maintenance windows. All efforts should be taken to prevent fatal errors which would cause the edition to crash and be rendered non-functional. The edition should also be able to handle a consistent amount of traffic but should not expect high volume.

Security

There are no security requirements outside of standard IP concerns (images should be secured in such a way so as to discourage a “right-click | save”).

Portability

Ideally, the edition should remain portable with all internal links remaining relative to the site. Hard-coded domains should be avoided at all costs in case the edition needs to migrate to another domain or university.