→ Digital humanities

Maintained by: David J. Birnbaum (djbpitt@gmail.com) [Creative Commons BY-NC-SA 3.0 Unported License] Last modified: 2023-01-13T19:34:47+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 the project must be designed to facilitate that research.

Digital edition and publication without an explicit research question 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 and methods and the research team. For a good example of this type of documentation see the Project 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, 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
Where appropriate, research conclusions and analysis should be displayed to the user visually, that is, with the help of graphs and charts. Other forms of data representation, such as lists and tables, are not always the most effective way of displaying useful and easy to comprehend information. 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 through the appropriate use of XSLT or XQuery.

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. Work in GitHub doesn’t have to be finished, but anything that isn’t in GitHub doesn”t count.

GitHub can be disorienting at first. 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 there and to advise should you run into difficulties 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 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 are linked (with <link> or <src> elements) from the <head> of your HTML. See the Attaching CSS to HTML section of our Introduction to CSS and method #2 in our JavaScript overview for details.

Unless your project mentor has okayed it, do not embed <style> elements in your HTML, do not use @style attributes in your HTML, and do not use JavaScript-oriented attributes like @onclick in your HTML.

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 frameworks (e.g., React, Angular, Vue) and libraries (e.g., JQuery) are not permitted

JavaScript frameworks and libraries are not permitted in this course, but it’s common and acceptable to copy small individual JavaScript functions or bits of CSS styling 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. Copying large amounts of CSS or JavaScript from elsewhere and modifying them in small ways for use in your project is not acceptable. Consult with your project mentor should you have any questions.

(JavaScript frameworks and libraries are commonly used in professional DH development, as is copying someone else’s code wholesale and tweaking it for local use. We prohibit those approaches in this course because one of our goals is for developers to understand what every line of code does, which doesn’t happen if someone else has written more of your code than you have.)

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 are looser (just BY or 0) and some are stricter, also prohibiting 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.