Maintained by: David J. Birnbaum (djbpitt@gmail.com) Last modified: 2023-01-13T19:34:47+0000
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.
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.
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.
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.
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 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 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/.
<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.
Boilerplate text, such as headers or menus that should appear identically on multiple pages, must be implemented using server side includes.
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.)
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.
@title
attribute of
the image or its container element, or including the URL as readable text on the
page.