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.