Everybody hates doing documentation. Anyone who claims to enjoy doing should be on some kind of watch list. Robin East (@insidedctm) asked the question on twitter today
“project documentation: “documents” on their own are totally inadequate. Wikis are barely better. Anyone tried something else?”
The most effective documentation experience I ever had was the first where, as an afterthought, we incorporated video.
Robin’s question prompted me to think back to when I left Delta Air Lines in 2002 after ten years. I had started at the air line working in an entry level clerks position in maintenance and ended my career there as an advisory architect in document management. An odd beginning but by the end I had touched every content management related project at the company and as you might have noticed I tend to collect opinions.
Despite the thousands of words in project documentation, presentations, java docs and visio’s I struggled to find an effective way to communicate and pass on more than just details.I wanted to convey the ideas and strategic rationale that guided my decisions across the separately funded and diverse applications spread over a decade.
Unlike many departures where you announce you are leaving and the guard meets you at the conference room door with a box, my resignation was completely amicable and just the next step in a career. Consequently they wanted to squeeze every bit and byte out of my brain they could in a two week period. There wasn’t time to write it all down so I opted for the oldest method mankind has for preserving information. Oral history.
Working from a basic topics list, over three days and sixteen total hours of white boarding I went through my experience and vision for content and document management at Delta. I covered everything from why we named docbases after planets, how certain attributes in the data model make cross system data flows auditable even though no one was asking yet and yes even the bad ideas that never went away.
Besides being incredibly cathartic for me the team was hopefully able to avoid some of the mistakes I made. I was able to give them insight into why I made certain design decisions. Project documentation often only describes the final form. Even iterative methodologies don’t do a good job of preserving the why behind a design point. Both technical and political motivations drive architecture but we seldom if ever capture things like, “the new VP came from an XYZ technology shop so that became a standard without a formal selection process” or that “all of the architecture templates originated at Citibank so finance metaphors are not in the docs for a reason and can be ignored.”
One of my mentors, Bill Wheat, had the idea to set up a video camera in the back of the room and record the sessions. I didn’t think much of it at the time since it was pre-youtube and I never thought much more about the tape. A year later one of the developers called me and said they had actually pulled out the video to help solve a problem. While describing the production implementation we captured a dimension of the system design process that is rarely preserved. As part of the question and answers we discussed what didn’t work as originally expected and had to be changed and that led to the resolution.
Today chalk talks and recorded webinars for knowledge transfer are common place but seldom formalized as part of the documentation for a system. While everyone reading this likely has digital video recording capability in their pocket there once was a time when that was not commonplace. We struggled then and now to find a balance for just how much needs to be written down. The informational density of video allows you to embed and intertwine multiple dimensions of context with the presentation of the same material in a far more efficient manner than text ever can. Sadly our methods for capturing design have not caught up with even the most basic capabilities of the systems they describe.
The measurement of how effective documentation is can be highly subjective but in talking with the team that remained after I left, those tapes surprised us all in how they were able to assist long after I had moved on. It is certainly unrealistic to think video itself will do more than supplement most familiar project documentation but even informally applied, experience proves it can enhance and enrich the understanding of a complex system. We should recognize the effectiveness of the medium and leverage it to capture more than just scripted demos but as a means to preserve the thought and decision making processes that go into a design.
My issue with video “documentation” is that examples are much harder to follow along with. I constantly have to back up and watch things to catch what was clicked where. And then if this is truly something like a “do it along with us” sort of document, the lack of being able to copy/paste important things is a nuisance.
Conceptual things could lend themselves better to video documentation.