Digital humanities


Maintained by: David J. Birnbaum (djbpitt@gmail.com) [Creative Commons BY-NC-SA 3.0 Unported License] Last modified: 2015-10-01T20:02:52+0000


Project directory and file structure

General

This tutorial is designed to guide you in creating a directory structure of your project site and in choosing clear, robust, and maintainable file names. The basic principle is that everything about your project, including your directory structure and file names, should be as clear and self-documenting as possible. Not only will this make it easier for all members of the project team to understand the structure and content of the site, but it will help you if you return to the project months or years from now, when you can no longer remember the decisions you made or the reasons behind them.

Directory structure

It’s easy to fall into a pattern of dumping all of your project files into your main project directory, since that’s the location that requires the least thought. If you have just a few files that may not be a problem, but otherwise your site quickly becomes chaotic. The details may vary from project to project, and your project mentor will assist you in assessing your individual needs, but the basic structure we recommend for projects is that the main project directory should contain only your HTML pages, and other files should be installed in the following subdirectories:

Some of these directories, especially thsoe for data and images, may themselves contain subdirectories that help you group your data in a natural way.

Directory and file names

Directory and file names should observe most of the same conventions as file names for homework assignments, such as:

You do not have to (and generally shouldn’t) include your surname in your project files; that requirement is only for homework.

Have a consistent filenaming convention. For example, if your XML documents are personal letters, you might use date_senderSurname_recipientSurname_number.xml, e.g., 2015-09-28_obama_biden.xml. If it’s possible to have two letters between the same persons on the same date, though, how would you account for that? The exact filename components and their exact order isn’t the most important thing; what’s most important is that you use the same convention consistently throughout your project.

Document your directory structure and your naming conventions unless they are truly self-evident. You can use a plain text file with a name like readme.txt, and put it in the main project directory. You don’t have to link to it because it isn’t for site visitors; it’s there so that future developers (including your future self, should you return to your project after a hiatus and no longer remember your conventions) will be able to make sense of the site.

Images

Image files should normally be jpg or png and no larger than required for your project. Full-screen images should be no more than 1600 pixels on the long axis. If you don’t already have a favorite image editor, you can convert large images to more appropriate smaller ones with Irfanview (Windows) or GIMP (Mac, Linux), both of which are freely available.

Fonts

If you aren’t comfortable letting your visitors’ browsers use their default fonts, you should specify a font stack. If you use uncommon characters that may not be supported by the fonts on the average user’s system, you can provide web fonts.