Wow.  That is a really buzz-wordy title.  I had better explain myself.

As a tool builder and user I have become really interested in finding ways to improve technical documentation, particularly for the tools we as digital humanists build to do our work.  Good documentation helps a project at every stage of its development.  But we all hate to write (or sketch) documentation.  Instead of thinking of documentation as a final chore, one more thing to do after the program works, maybe we could integrate it into the process of the developing the software.  Highly commented code and up-to-date diagrams would dramatically decrease the amount of time it takes to put together a useful README file once the coding stops.

I see documentation as a chance to explain our work as digital humanists.  Writing good documentation requires getting into the mindset of your users (often non-technically trained humanities scholars) and explaining what you’ve done from their point of view.  As educators, this is a familiar exercise.  We can teach our colleagues and students through how we explain our projects.

If we are building open source tools we will also encourage a community of users by providing them with a helpful place to find answers.  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.

I’ve created a schema visualization tool (DAVILA) to help me create better documentation for my own relational databases.  If anyone else has suggestions I would love to hear them.