One point I struggle with is when to write a decision record. There are many decisions that go through without us even realizing it was a decision, sometimes it was just a reply to a comment, or something said on a meeting, which you put on the code and boom, a decision, usually logged only on the “why” of a commit message
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”?
Anything that is related to "why" related to _changes in_ architecture and domain usually goes in for me. e.g.
- 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.
In talking to my team, my advice has been "whenever it will be useful", which is of course a bit glib but I don't think we want hard and fast rules.
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.
We’ve started to do this when it comes to stuff that is architechtural significant, for example team A decides to event-source foo. Or team B opts to write microservices.
Also - anything infosec related goes through an ADR process.
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.
Writing is pretty easy, reading is the hard part. Between the ridiculous amount needed to read, plus the fact that maintaining up-to-date information is really difficult and how that makes reading even worse ("Should I bother reading this when it is out of date, or just talk to the person that has it all in their head?").
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.
I'll agree that reading is hard, but I think it's also fair to say that reading good writing is easier. Then, we can say that it's hard to write well, and it follows that reading most writing is hard (including this comment probably...)
I write copious documentation for everything I touch. My colleagues do not bother to read them, nor do they try to learn from my practices. I continue to do so, everywhere I go, because I design my applications by writing documentation first, or alongside my code. It helps me think. I do not think that tools are necessarily the problem. I use README.md files mostly after trying to use Sphinx and Notion. This has a very low entry point. But they do not care. They insist on using one time hacks and never documenting things, even Root Cause Analyses.
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.
If you don't have the skills, power, or desire to improve the culture where you work, and it consistently bothers you, then go work somewhere that's already closer to what you want.
Amazon and Google are good examples of companies that make heavy use of written design documentation and post-mortems.
I find cross-references to be a big win. I've taken to using `@@{subject}` syntax as anchors and `^^{subject}` as references, anywhere in comments, docs, etc, within a single repository. Then I set up tooling that checks that every reference has a (single) corresponding anchor, and tooling that surfaces in github PRs the other relevant bits when an anchor or reference shows up in the (changed or context) lines of a diff.
Notion has worked okay for us in the past, but recently we’ve moved to just using markdown documents in Git. It’s just as searchable, and stays closer to the code. RFCs et al. are submitted as PRs.
I can heartily recommend Obsidian[0] as a way to augment "markdown documents in Git". It lets you cross-reference between your markdown documents using [[wiki links]] so you can start building a knowledge graph.
This needs a prefatory "Tools for a Culture of Reading".
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.
Or maybe "tools for promoting a culture of writing".
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.
I've worked with a guy who simply could not understand what he had to do if told in writing... email, IM whatever. When you told him in conversation he got it and did decent (not brilliant) work.
He was a programmer. You'd think writing code all day would allow you to understand writing...
I worked with a similar guy: he would not do anything without first having a conversation about it. According to him, the act of writing notes based on a conversation helped concepts stick in his mind more durably than simply reading what others had written. While I'm sure there's some truth to that, it's absolutely possible to synthesize written thoughts in one's own words without directly interrogating the author. I suspect that the skill of "critical reading" is the missing link here.
I wonder if you and I and the sibling commenter are talking about
dyslexia without realising it? I don't know much about it. A friend of
mine has a similarly wired brain. Definitely there's a spectrum from
very language orientated minds to those who greatly prefer picture,
sound and face to face spoken communications. I wonder if smartphones
and iconic interaction are making us all more dyslexic?
> I wonder if smartphones and iconic interaction are making us all more dyslexic?
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.
I'm looking for another word, that (ironically) I can't find :)
Something to mean a disposition to think and communicate (perhaps in a
superior way) without recourse to language. Non-linguistic? Illiterate?
(that sounds a bit harsh/critical). But you see the space I'm shooting
for (divorce the idea of illiteracy from "stupidity").
> 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.
Well, one angle is to qualify the use of the term "literacy", as in "visual literacy". Here is an article about the movie Pacific Rim that pointed out how much of the story (or rather, backstory) was visually communicated to audiences via production and character design in ways that entirely whoosh over the head of most viewers focused on dialog and acting:
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”?