Digital humanities


Maintained by: David J. Birnbaum (djbpitt@gmail.com) [Creative Commons BY-NC-SA 3.0 Unported License] Last modified: 2021-04-23T00:53:48+0000


Project checklist

Course projects must observe the following guidelines, which are derived from Best Practice in professional digital humanities development. We’d suggest beginning to implement them as early as possible in your project development, so that you won’t be fussing with the details as the due date approaches. If you need more information about any of these guidelines, ask your project mentor or any of the instructors.

Your website must communicate your research questions, methods, and results

Projects must articulate and explore a research question

Projects must articulate and explore a research question, and to the extent that they involve textual editions with exploratory tools, the developers must use those tools to conduct their own research. Digital edition and publication is an important professional DH activity, but in this course we also want the projects to provide experience in exploring research questions.

Explain what you do and why

Different projects will require different types of documentation, but all projects will normally say something about the research goals, methods, and the research team. For a good example of this type of documentation see the Projects menu items at https://gams.uni-graz.at/context:corema.

Avoid technical jargon

You should avoid technical jargon. Your target users are typically people interested in the content, that is, in the subject area, rather than in the technologies. This means that, for example, if you provide a concordance feature, it’s better to call it concordance than KWIC, since the latter term (informatic jargon for keyword in context) won’t mean anything to most humanists. Nonetheless, it’s common in DH projects to include some discussion of the technology, often on a separate page, so that it doesn’t interfere with the use of the site for humanities research, and technical jargon is acceptable there.

Use graphic visualizations where appropriate
Research conclusions and analysis should, where appropriate, be displayed for the user through graphs or some other form of visual representation in some capacity. Other forms of data representation, such as simply listing numbers, are generally not as efficient in displaying useful and easy to comprehend information to the user. In addition, the act of creating the graphs can be helpful in analyzing your results. Chart and graph representations of your information must be in SVG that you create using XSLT or XQuery (that is, no loading the data into Excel, letting it draw the picture, and capturing an image).

Workflow

Project teams must make weekly progress

While working on your project throughout the semester, you must complete (or at least make significant progress on) all weekly assignments as discussed in group meetings with project mentors. The files resulting from these weekly assignments must all be pushed to GitHub in order to maintain, track, and preserve progress. GitHub can be a bit disorienting at first, but your instructors are committed to ensuring that all students learn how to use it, and we are available to help you get your project configured on GitHub and to advise should you run into difficulties with GitHub over the course of the semester.

Project website: code

Project space must be organized

Project directories should typically be organized with separate subdirectories for data (subdirectory name data), css (css), JavaScript (js), images (images), and server side includes (inc). Typically the only files (non-directories) in your project root directory should be HTML pages. More complex projects benefit from more detailed structure, and you should review your own requirements with your instructor or project mentor.

All files (XML, HTML, CSS) must be valid and browser-independent

All XML files must be valid against your schema. You should validate them inside <oXygen/>.

All HTML pages on your project site must be valid HTML5 using XML syntax. See the discussion of what the means at our HTML basics page (where you will also find instructions about how to create valid HTML5 in XML syntax when transforming XML using XSLT). You can validate your pages at http://validator.w3.org.

All CSS files on your project site must also be valid. You can validate CSS on line at http://jigsaw.w3.org/css-validator.

Your pages must work in all major browsers, which we are defining, a bit arbitrarily, as the most recent versions of Edge (Windows only), Firefox, Chrome, and Safari (MacOS only). Support for mobile devices is not required, but if you can provide the functionality you want while supporting touch devices, target Safari, Firefox, and Chrome on iOS and Chrome and Firefox on Android devices. You can check for browser support of specific features at https://caniuse.com/.

CSS and JavaScript should be in separate files, linked from your HTML (not in the <head> and not in line)

Unless there is good reason to do otherwise (ask your project mentor or an instructor if you aren’t sure), all CSS and JavaScript must be in separate files, that is, not in the <head> of your HTML and not in attributes inside the HTML file. See the Attaching CSS to HTML section of our Introduction to CSS and method #2 in our JavaScript overview for details.

Text that appears on multiple pages (e.g., menus) must be in SSIs

Boilerplate text, such as headers or menus that should appear identically on multiple pages, must be implemented using server side includes.

JavaScript libraries (e.g., JQuery) are not permitted

JavaScript libraries, such as JQuery, are not permitted in this course, but it’s common and acceptable to copy small individual functions from other sites. When you do that, though, you must include the URL of your source site, typically as a comment within your JavaScript file. (JavaScript libraries are commonly used in professional DH development. We prohibit their use in this course because one of our goals is for developers to understand what every line of code does, so that they can modify it as needed. This isn’t possible or practical with large libraries.)

Project website: documentation

All projects must include a license statement

All projects must include a Creative Commons license statement, either on all pages (perhaps in a small-type footer) or on the main page. Most DH projects use a BY-SA license; some also prohibit commercial reuse with BY-NC-SA. The choice of license is up to you.

Content from other sources must be credited
All content taken from external sources, such as images you find on the web, must be credited in some way. Possible methods include making the image itself (or its container) a live link to the source site, putting the URL for the source site in the @title attribute of the image or its container element, or including the URL as readable text on the page.