Humanist Readable Documentation

May 21st, 2010 |

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.

Comments Feed

One Response to “Humanist Readable Documentation”

  1. joanna Says:

    As a point -and -click enthusiast from way back, I appreciate your project. As a community college professor, I am always trying to convey usability in a much simpler way than many programs allow.

Search

  • Recent Comments

    THATCampers can use the blog and comments to talk about session ideas. Follow along by subscribing to the comments feed and to the blog feed!

    • thuyanh: A friend and I have actually made a video response that defends the “dumbest generation” and we...
    • Steven Hayes: Hi, just read your “project retrain” description as part of my background reading for...
    • Peter: Just curious: Is there a version of the National Register Nomination Form in some kind of database format,...
    • Samuel Teshale Derbe: This is excactly what I have been looking for.I have been recently invited to contribute to a...
    • plr articles: Just added more knowledge to my “library-head” :D
  • Twitter

    Here's what others are saying about THATCamp on Twitter

    • No items

    All Posts

  • THATCamp Prime Collaborative Documents
  • THATCamp Prime evaluation
  • New session: The THATCamp Movement
  • THATCamp on Flickr
  • Visualizing Subjectivity
  • More Twitter Visualizations
  • Remixing Academia
  • What THATCampers have been tweeting about (pre-camp)
  • Late to the Stage: Performing Queries
  • Humanist Readable Documentation
  • Zen Scavenger Hunt
  • The (in)adequacies of markup
  • One Week, One Book: Hacking the Academy
  • Analogizing the Sciences
  • Digital Literacy for the Dumbest Generation
  • Teaching Students Transferable Skills
  • Modest Proposals from a Digital Novice
  • Creative data visualizations
  • OpenStreetMap for Mapping of Historical Sites
  • soft circuits
  • Mostly Hack…
  • A Contextual Engagement
  • ARGs, Archives, and Digital Scholarship
  • Playing With the Past: Pick One of Three
  • DH centers as hackerspaces
  • All Courseware Sucks
  • HTML5
  • Dude, I Just Colleagued My Dean
  • The Future of Interdisciplinary Digital Cultural Heritage Curriculum (oh yeah, and games as well)
  • Project "Develop Self-Paced Open Access DH Curriculum for Mid-Career Scholars Otherwise Untrained"
  • what have you done for us lately?
  • Digital Storytelling: Balancing Content and Skill
  • Visualizing text: theory and practice
  • Plays Well With Others
  • Citing a geospatial hootenanny
  • Reimagining the National Register Nomination Form
  • documentation: what's in it for us?
  • Sharing the work
  • Digital Humanities Now 2.0 and New Models for Journals
  • Finding a Successor to Paper and Print
  • "Writing Space"
  • From Scratch
  • Cultivating Digital Skills and New Learning Spaces
  • Surveying the Digital Landscape Once Again
  • Building and designing projects for long term preservation
  • Collecting the Digital Story: Omeka and the New Media Narrative
  • Design Patterns for DH Projects
  • Chronicling America: They gave us an API. What do we do now?
  • Social Media and the History Non-Profit
  • THATCamp-in-a-Box
  • Teaching Collaboration
  • Geolocation, Archives, and Emulators (not all at once)
  • The Sound of Drafting
  • The Schlegel Blitz ("Only connect…")
  • Text Mining Scarce Sources
  • Applying open source methodology and economics to academia
  • What I'd Most Like to Do or Discuss
  • Hacking ethics for edupunks
  • Mobile technology and the humanities
  • Audiences and Arguments for Digital History
  • Open Peer Review
  • Who Wants To Be A Hacker?
  • Please advise
  • Greetings from the new Regional THATCamp Coordinator!
  • 2010 Applications Open!