- What was the culture of the team?
- What were the designs/philosophies of the original architect?
- How can we make those thoughts more explicit?
I found the moment to be eloquent, and reminiscent of an episode of SE Radio, where Dave Thomas uses a similar metaphor: code maintenance ultimately requires us to understand a culture by analyzing artifacts. Call it software archeology.
Artifacts
We can all name the usual artifacts: an architecture document, UML diagrams, sequence diagrams, and so on. If we are lucky, perhaps there are tests.
Unfortunately, all too often, documentation is formal and poorly written. Reading it for culture is like trying to understand a society by reading its laws: useful, but abstract and without soul. Worse, the documentation may be out of date and only vaguely relevant.
A Potential Solution?
As consumers, we spend untold amounts of money on video equipment, which is both powerful and easy to use. We think nothing of uploading staggering amounts of video to the cloud, documenting our lives, and yet in the corporate environment, nothing. This strikes me as absurd.
In addition to striving for new wikis, language constructions, and formal diagrams, why don't we use video?
Consider this: what if the team lead gave a 1-hour architecture overview, once per release, and it was recorded and checked-in to source control? What if s/he took an afternoon to make a screencast of a random walk through the IDE? That is, what if we treated video time capsules as project artifacts?
For future software archeologists, they would be worth their disk space in gold. Imagine the simple nuances and gems that are so difficult to express otherwise (e.g. "yes, we are bending the usual use of aspects here, but there was a trade show deadline. We hope to address this technical debt").
Note that in my vision, the production quality would be low: these could be one-take, banzai attempts. Naturally, no one can possibly explain all of the corners of a code-base, but this isn't about corners: this is about culture.
Counterpoint
This strikes me as so obvious, that I must be missing something. Perhaps I am simply naive. Arguing against this idea, the main deterrents that I can see:
- Companies may not be prepared to buy and manage video equipment. In terms of acquisitions and stewardship, it just isn't part of their DNA.
- Managers may fear that video is somehow less secure than source-code.
- For highly regulated industries, what happens if a team-lead describes a design flaw or technical debt? Could this be a legal liability? (This could be a major deal-breaker, but certainly not for all companies?)
- There is no incentive for a team to prepare others for future maintenance. Even if video time capsules are effective, the status quo is good enough, and between leads, developers, and managers, no one will demand better.