Technical diagrams are wonderfully compact ways of conveying information about extremely complex systems. But they only work for people who have been trained to read them. If you design a database for a historian, and then hand him or her a basic E-R or UML diagram, you will end up explaining the diagram’s nomenclature before you can talk about the database (and oftentimes you run out of time before getting back to the research question underlying the database). This removes the major advantage of technical diagrams and can also create an unnecessary divide between the technical and non-technical members of a digital humanities development team.

I have become fascinated by how documenting a project (either in development or after release) can build community. I’m not just talking about user generated documentation (ala wikis), but rather the feeling created by a diagram or README file that really takes the time to explain how the software works and why it works the way it does. There is a generosity and even warmth that comes from thoughtful, helpful documentation, just as inadequate documentation can make someone feel stupid, slighted, or unwanted as a user/developer.

As one possible solution, I have written a database schema visualization/annotation tool called DAVILA.  It is written in Processing with the toxiclibs physics library and released under GPLv3. DAVILA takes in the database’s schema and a pipe separated customization file and uses them to produce an interactive, color-coded, annotated diagram similar in format to UML.  I wrote the program to help me describe my dissertation database, but also in the hopes that it could spark a larger conversation on how to make technical diagrams accessible to non-technical people.  The project page is www.jeanbauer.com/davila.html.

Ronda Grizzle has already posted about the importance of generating basic documentation for maintenance of projects.  Perhaps those of us interested in issues of documentation could put our heads together and come up with some principles for documenting a project from start to finish.

In pondering this proposal, I’ve come up with four basic types of documentation that I think are relevant to digital humanities projects.

• supporting creation of scholarly output
• supporting reporting to funding agencies or academic departments
• allowing sharing one’s research methodology with other scholars
• informing and educating system administrators about the system-level requirements of the software itself

All these types of documentation are important, but I think it’s time to start talking with each other about that last type. We all want the results of our work to survive and mature, and one of the best ways to insure longevity and sustainability is to properly document system-level requirements—software dependencies, negotiated service level agreements, database design, etc.. Improving our communication with our IT system administrators ensures that we can meet as equals, moving away from handshake deals and hopeful bribery with baked goods as a means to attempting get the support our projects require.

We’ve learned some hard lessons at UVa Library about the sort of documentation and process definition that are required for long-term support of our digital tools and interfaces, and I’d love to share these with anyone who’s interested. Just as importantly, I’d love to learn from other attendees experiences creating usable system documentation for their projects.

related to:  karindalziel’s  session proposal