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.
The other advantage to documenting as you go is that it’s easier for other people to understand the process (and learn from it). Plus, there’s always the “hit by a truck” principle.