Trump 20: Commentary

Image from Wikipedia

In the standard Tarot, the 20th trump card is The Last Judgement. For computing, the 20th trump is Commentary, the human language documentation and notes that accompany a computer program or system.

To understand computing systems, we rely on messages and guides from folks who have come before us. Architects draw diagrams we consult. Authors of programs write their reasoning next to the results of their decisions. What is illegible from the system itself is instead written in its margins.

Of course, commentary is unreliable in ways that the source code of the system itself is reliable: while comments tell us what the author intended, the source code tells us what is actually happening. Comments are wishes that we hope align with reality. As systems change, comments that once helped can lead us astray, or just distract us from the real things in front of us.

How do the stakeholders in your system communicate? What are the artifacts of that communication? How long do they live? Long enough? Too long? How does the society of your system align with the system’s mechanical operation?