What is it? A software development logbook? And what to write into?
Let’s ask ourselves the following questions:
On what basis do you make decisions, when and how?
How do you know when, what should happen?
How do you measure how your idea is doing?
William Edmund Hick (1912–1974), British psychologist, says on the subject of decisions: “In psychology, the time to make decisions is considered proportional to the number of decision possibilities”.
Let me take you into three areas with certain parallels to software development that we can learn from:
In the shipping industry
There is the obligation since 1999 to keep a logbook for each sea-going vessel. In addition, this obligation is anchored in the international agreement on maritime navigation and is also reflected in the Navigation Act. Here is clearly regulated what must be in a logbook, for example: Safety deficiencies, special incidents and justification in case of omitted assistance. In addition, it is also regulated how to handle the logbook, for example: Deletions must still remain legible, Deletions must be dated…, It must be recognizable when one or more pages have been removed. If parts of the record are made in nautical charts… Acknowledgement and signature of the ship owner at least every 12 months. Retention requirement of the ship owner for a period of three years.
Now this sounds quite harsh and bureaucratic but certainly has its purpose, if in this case even an international agreement exists. Cool is also the method by which a captain assesses how his project is doing, he walks the deck and feels the mood on the ship. If this is good, there is no reason to worry. *https://en.wikipedia.org/wiki/Logbook_(nautical)
In research
Record sections of the field being researched to record findings and measure whether or not assumptions made are accurate. The health of a project is decided by the people, not solely by the technology.
*https://en.wikipedia.org/wiki/Field_recording
In architecture
Every awake architect creates them when he walks his building sites to react to misunderstandings of his ideas. Intercepting and utilizing the unforeseen in a sustainable manner is part of the craft of every architect.
*30x40 https://thirtybyforty.com/blog
If we assume that the development of software systems is an explorative endeavor. It is not so far-fetched to live this practice also as software architects. After all, we are also dependent on recognizing when, if and above all how our ideas are implemented. So it doesn’t hurt us to have a small tool with us to be able to react in an explorative environment to shape the further future.
(Software) Architecture Field Records!
This is what it looks like, the logbook entry:
Date:
Project: <project, software section or module>
Observation: What did you observe? Was there anything particularly horrible or and even better something great? Also observe the people and their mood. Did knowledge emerge that should be shared?
Health: <selection: How is the project doing> “well”, “ok”, “unexpected”, “not so good” or “bad”.
Consequences: (consequences): List of all positive and negative consequences.
Reaction: List what should be done next and what you intend to contribute.
Important to know:
AFRs are valuable because of their continuity.
AFRs give the exploratory process of software development the opportunity to react in a sustainable way.
AFRs create the space to shape the future.
Not so bad in my opinion and I prefer to document less than necessary. However, and necessarily, if I look after several, or very complex systems, they help me and the team immensely. Think about, only to have a daily, round about 15 Minutes with each team to get information, or a architecture council if lucky enough in time and budget. If necessary for you, let me know about the gift of feedback, or even more active participation in the topic. I would be very happy to here from you.
a Monkey Squad finest software craftsman shipment idea
see you soon and farewell
Janosch