Tools for a Culture of Writing (2021)
matt.blwt.io
matt.blwt.io
What would be the rule of thumb, which decision size is big enough to worth a DR, what triggers “I have to write a DR for this”?
- Why did we end up not using FIFO queues here?
- Why did we decide to disable users who did x?
- Why did we create a new module rather than updating the existing one?
I say "changes in" because we'd often write an architecture document at the start of a project. That document has the initial assumptions and reasonings. A decision record documents inevitable changes to the plan as we find out more about the problem space.
I also find having a person directly responsible updating the record is the best, if the project doesn't involve too many people.
If not, then start one as that's the easiest way to review what the concerns of the day were back then, and to begin to see where having history starts paying dividends.
Otherwise, something like the principle of https://en.m.wikipedia.org/wiki/Prudent_man_rule -- ie. were you parachuted into this project, which decisions would need rationales?
It's going to be more true of things that are harder to change, more true of things that touch more places in the code, more true when decisions are higher risk, more true when reasoning is less obvious.
I also think we should err on the side of writing too many ADRs, and writing ADRs that are too lightweight. There's some implicit pressure that if we're writing down our reasoning we'd better make sure it's good reasoning, but it's simultaneously true that some decisions don't deserve a lot of deliberation and when a decision didn't get a lot of deliberation we would like to know that down the line. If we capture some number of ADRs that say "decided XYZ because shrug", then down the line when we're inevitably bit by some bad decisions, we can look at whether those were disproportionately the ADRs that got less thought.
Rule of thumb: are we, or someone else, going to second guess this decision in a year or two? If it feels likely an ADR is in place.
Written works have an over-exaggerated finality to them. They can be good for capturing some of the reasoning behind a decision, but even then, it is only somewhat spotty.
Like others have said here, we need ways to improve and build a culture of reading and writing documentation. Our CTO says he wants to build this, but there's some disconnect.
Amazon and Google are good examples of companies that make heavy use of written design documentation and post-mortems.
The hard part is the library. How do you organize all these records so they might be usable by someone two years later.
[0]: https://obsidian.md/
How many colleagues will do a literature review before starting something? How many will take notes and try to understand the history of how everything got to be the way things are?
RFCs and docs are great; it just seems like they're usually secondary to the functional docs of throwing code over the progressively higher walls of git-hooks, build tests, and ops monitoring.
Increasingly I find I may be in a "minority of writers" in org teams who are primarily visual, memetic, kinetic and leave only fragmented records in mixed medias. I've also encountered younger engineers/programmers who pretty much cannot type! (only thumbs on a phone screen) - not even hunt and peck... just staring at the keyboard like it's an alien technology.
I actually understand this way of being. Using a visual programming language like PureData/LabView (dragging cords) and interacting via sliders, visual indicators/meters all day long I've inhabited the zone where I have been solving hard DSP problems in a visual-kinetic way, and hardly "thought in language" for hours on end. If someone comes into the workshop and asks me a verbal question it takes a few seconds to reboot that part of my head in order to speak.
But what I notice is that this mode of being in the world (Dasein?), is becoming dominant as people wander around all day, smartphones in hand (I don't use them), and so there's fewer moments when people process what they are doing/thinking qua language.
So for example; As desktop person who spends a good deal of the day interfacing to the world through a full keyboard and screen my fingers and textual brain are engaged, but some colleagues may do things like send a photo of a schematic taken on their phone, no accompanying text or explanation, not even a relevant subject line. So I get that they are not "thinking" in language. I wonder if I am part of a shrinking/dying culture of symbolic communicators.
He was a programmer. You'd think writing code all day would allow you to understand writing...
No. Dyslexia is an actual learning disability, it isn't a lack of skill, aversion, or a missing habit. Dyslexia causes the reader to have difficulty recognizing words by, for example, scrambling letter order, and making it harder to distinguish similar letters (eg. confusing the mirror image letters b and d, or p and q), and similar visual confusion. It has very little to do with an inability to comprehend sentences.
Smartphones have actually increased the amount of text people read and write, but it is true that for most people little of that time is spent on text in longform formats rather than texts, tweets, memes, and shorter blog posts.
Certainly people who don't read and write longer essays and similar documents habitually are less likely to reach for that sort of reading and writing as tools for thought, and may not be as skilled in their use when they do, but that can generally be remedied with practice.
But none of that means that people are 'more dyslexic'.
There are other mental configurations (like ADHD) that make digesting longform text more difficult; those can sometimes be accommodated by using different (generally more atomized) documentation formats instead of continuous longform prose. Atomized formats will generally also help non-habitual readers, non-native speakers, the young, non-experts, and so on.
Of the four documentation types (tutorials, how-tos, explanations, and reference), only one (explanation) will tend to be expressed as longform text, but it doesn't have to be. Shorter explanations, or breaking the document up into shorter passages, is often well worth doing. There is no downside from making documents easier to digest. For the other documentation types, longer passages are a bit of a "smell" that should be eliminated if possible.
As in other contexts, accommodating a broad range of ability in people produces benefits for everyone, including for those who are more able.
> As in other contexts, accommodating a broad range of ability in people produces benefits for everyone, including for those who are more able.
Yes, I'm all for that, minus the use of "more/less able" (and say so in my example of "coding without code"). But returning to the OP essay, there's a problem that the structures of business and politics, formalisms, records, bureaucracies, project management.. are deeply rooted in the written (and often tortuously long-form) culture that mobile technologies, short attention spans and nonlinguistic semiotics are supplanting.
And to me that also suggests a widening class-gap, or rather a growing gap between modes of understanding the world that determine who are deciders or followers. It's more to do with technology use than any level of education or neuro-atypical "disorder" (the way you use "dyslexia" in a strictly "medical" way.) I hope that makes sense.
https://www.stormingtheivorytower.com/2013/07/the-visual-int...