The Quasi-Forgotten Software Scribe
The Quasi-Forgotten Software Scribe
A scribe is a person who serves as a professional copyist, especially one who made copies of manuscripts before the invention of automatic printing.
Remember Bob Cratchit in A Christmas Carol, toiling away on the books at the august firm of Scrooge and Marley, finger-less gloves on his hands to keep them from freezing between entries? Watching it will start us to thinking about old Bob and all the other “clarks” who kept the records for so many enterprises over the centuries. These scribes were really the computers of their day. Without them, businesses would have been thrown into bankruptcy and whole industries cast into chaotic disarray. Their real power and importance went far beyond either their meager wages or their lowly status. Things are hardly different today. Those who keep the records are held in low regard.
In their pens and markers and keyboards can reside the power to spell success or failure for software development.
Software development groups, if they keep any records at all, are likely to limit their files and notes to results and conclusions, the work product or deliverables generated by their efforts. Programmers, especially, are loathe to write down anything other than the code itself unless they are threatened with a fine or imprisonment. Getting them to draw diagrams can be akin to getting an elephant to do pencil sketches. After all, isn’t good code self-documenting?
Vital Statistics
This view tends to lose sight of vital information. In general, when only the work product is preserved, we know what we got in the end but not how we got it. How the software was generated, the decisions along the way, are essential parts of the process. Do we want to trust to memory? Do we care only about our mistakes or do we also want to learn from them?
When only the work product is preserved, we know what we got in the end but not how we got it.
A particular problem with groups that keep only the end product of software development is that they do not preserve a record of what they didn’t do. Often it can be as important to know what approaches were rejected and for what reasons as to know which were selected. This is vital information to have when it comes to future versions or systems or to preserve for when the current system goes down the tubes. You have probably had occasion to examine some of your own code some years or months after you wrote it. Have you ever had the experience of spotting something that you just knew must be wrong and you wondered how the software ever squeaked by without crashing because of it? If you gave in to the temptation to “correct” such a latent bug, then you may have found that “fixing” it brought the system to its knees. The problem, of course, is that the code only looked wrong, but the code did not explain why it was actually right. It does not help to have a comment in the code that read, “Do not change this decision; it looks wrong but is really right.” If the programmer knew why it was right and why the alternative was wrong, then why wasn’t that logic recorded in the comment? We need to know what alternatives were considered and rejected and why if we are going to be able to maintain a system for years or build its successor five years later after all the original development staff are long gone.
The problem is that the code only looked wrong, but the code did not explain why it was actually right.
Business consultants today talk about organizational learning as a key to enterprise success over the long run. Organizations, like individuals, can learn from their experiences, accumulating knowledge and improving performance. To the extent that organizational learning resides solely in the brains of individual employees, the organization is vulnerable. Employees get sick, take vacations, and change jobs. They forget. In truth, the learnings of an organization are embodied in its records, its policies, and its practices or processes, not solely in its people. The more we document and record what happens as we go along, the more likely such learning is to survive the group or team that produced it.
Scribbles
The function of the scribe or recorder on a software development team is to be responsible for the team’s collective memory, the repository of its work product as well as of the processes that generated the results. The scribe keeps the books. In the Structured Open teamwork model devised independently by Rob Thomsett and Larry Constantine, the role is referred to as Information Manager. This newspeak title is intended to raise the status of the role, somewhat akin to the ad for a garbage truck driver calling the job a “sanitation transport engineer.” It is easy to see the scribe in a meeting as a mere functionary, hardly more than a human dictaphone, but this position actually draws on many skills. You can’t keep effective notes on things you don’t understand, so software scribes have to be fully trained developers. And they must know how to record and manage information for a real development project. The quality of the records determines the quality of the group’s permanent collective memory of what happened and how. A scribe who captures a full account of what the group did, complete but without excessive detail, well organized and understandable, is a team member worth his or her weight in code.
You can’t keep effective notes on things you don’t understand.
A good group memory must carry a lot of information. Some of this is volatile or temporary storage, some is permanent. Some of it is active and worked with dynamically in meetings and the day-to-day tasks of the team, while some is more passively filed. The information management functions can be divided for convenience into session memory and project memory. Session memory consists of the records generated and manipulated during group sessions, whenever the team is meeting and solving problems as a group. Project memory covers the permanent records and documentation produced and used by the group. It includes the work product, which means not only code but also all the design and analysis models and documents generated along the way to the code. Project memory also covers inputs to the project, such as requirements and specifications, and other background documents. Managing the project memory really requires a librarian, and often the role is known by that title.
Modular Memory
An essential part of the session memory is the process record, a log of the discussions and decisions made by the group. The idea of keeping process records is probably new to most software development groups, but it has been a part of meeting management for decades. In creating a process record, new scribes tend to fall into one of two traps. Either they try to write down everything as if they were taking dictation, or they wait until the group reaches some conclusion and just summarize. For technical teamwork, a “he-said/she-said” kind of record is neither necessary nor ideal. A good process record keeps track of key events along the way to an outcome, especially the alternatives considered, decisions made, and arguments presented. These are essential contributors to group learning and may be invaluable when it comes time for a project “post mortem” or design review.
Do-Lists
For software development, a continuous and unstructured process record is not ideal. Some categories of information are so commonly generated by development teams working in collaborative sessions that they warrant separate recording for special attention. It is useful to keep a “do-list” for noting those things that come up in discussions but are not acted on right away. This alone can justify the frustration of keeping session records because it can save projects from those embarrassing oversights that tend to show up in systems integration or after product shipment.
Deferred Decisions Lists
A good session memory also records deferred decisions, which are best kept separate from the heap on the “do-list.” A formal storage place for deferred decisions can also speed up decision making. Instead of wasting time with endless discussion driven by inadequate understanding or missing information, the group can put the issue on the deferred decisions list. Often, by the time the group returns to the issue, enough has been learned to make a swift decision.
Parts Bin
A third special record that proves useful on development teams is a “parts bin,” where bits and pieces of bright technical ideas or partial solutions can be set aside temporarily without disrupting the main thread of discussion.
Reject Bin
The “reject bin” is just the opposite, a place to note all those unused ideas and paths not taken, along with that vital rationale for rejection.
All four of these special records—the do-list, the deferred decisions, the parts bin, and the reject bin— serve to record things that might otherwise be lost or forgotten. They also help the group to make efficient use of time. By recording digressions and distractions in one of these specialized bins, the group can stay on track with the main problem without losing useful information. It can also keep a group from getting stuck on discussions that are going nowhere. Instead of more wheel-spinning, an issue can be moved to one of the “bins” for later attention. The bins themselves also serve as quality assurance mechanisms. By the end of a project, everything in the bins must have been crossed off or otherwise accounted for.
So who is the lucky person who gets to be a scribe?
Some approaches, such as Joint Application Design, bring in outside facilitators and scribes, trained specialists who are good at it and can free up project members to concentrate on creating software solutions. Some groups permanently assign the job to one person on the team, often a junior member or trainee. For most software development teams, a compromise between these approaches can be more effective.
The function of information management can belong to the team as a whole, with the actual responsibility rotated among members of the project team.
No one is exempted from playing the scribe, but no one is stuck with the job for too long. The job of Session Recorder is one that may actually change from moment to moment with the flow of the meeting, or it may stay in one set of capable hands for an entire working session. However, for the sake of sanity and good teamwork, it probably should switch at least with each new meeting. In longer meetings, it probably should rotate at least every hour or so. The truth is that being a good scribe takes extraordinary concentration, and very few people on the planet actually enjoy the role. Taking care of the archives, the off-line or project memory, can be rotated less frequently. Passing the torch on a daily basis would only ensure chaos or non-performance. During a one-year project, the overall job, what might be termed the Project Information Manager or Project Scribe, might change hands only once or twice at the most.
References:
- Constantine on Peopleware by Larry Constantine
- Wood, Jane and Silver, Denise; Joint Application Development, John Wiley & Sons Inc, ISBN 0-471-04299-4
- Structured Open Teamwork Model by Rob Thomsett and Larry Constantine
- https://en.wikipedia.org/wiki/Scribe