31–40 of 64 posts
So this is somewhere between code comments and Confluence pages. Seeing as even comments can get stale, how accurate do these docs stay? The added focus on "why" instead of "what" seems more resistant to cruft.
I think the fundamental idea behind this is that "every decision must be rationalized", which is fine, but in reality it's difficult to pull off in my opinion. Because people (including myself) are so easily fooled, I'm afraid that it's often the case that we deliberately ignore certain (inconvenient) facts or unconsciously distort things. If we are really trying to rationalize ourselves, the decisions have to be rev…
The point is that, in the future, you can look at the doc to know why a decision was made.
You can then use that info when you are faced with deciding to make changes; maybe the circumstances changed and you now want to make a different decision. Or, maybe there are reasons that were forgotten, and you really should keep the system as it is.
You might read the ADR and realize the reasons were arbitrary and there wasn't a particularly good reason to choose what they did... that is good info to have!
I feel like this is a way to avoid a Chesterton Fence situation.
https://en.wikipedia.org/wiki/Wikipedia:Chesterton%27s_fence
In any case where you're making a non-default choice in software, it needs to be explained in an easily-discoverable place so a developer that's looking at the project and trying to understand the why of something can see it.
Too often I block PRs with confusing code and ask why it was done this way and the developer swings by my office or gets defensive and I have to say "no, I'm not attacking your code as being wrong, and I don't want a verbal explanation as to how it works. I want the decisions that led you to do it this way to be documented".
...
But actually usually the code is just wrong.
I think the fundamental idea behind this is that "every decision must be rationalized", which is fine, but in reality it's difficult to pull off in my opinion. Because people (including myself) are so easily fooled, I'm afraid that it's often the case that we deliberately ignore certain (inconvenient) facts or unconsciously distort things. If we are really trying to rationalize ourselves, the decisions have to be rev…
For example, my father was in a meeting (snoring, as was his right as the longest serving member of the organization) when he overheard someone say, "We shouldn't change that, it's probably done that way for an important reason." Luckily, he woke up and interjected, "No, I picked that arbitrarily 30 years ago. Go ahead and change it." It'd have been better if he had written down the rationale, but don't judge. He wrote down plenty over the years.
[1] https://firstround.com/review/square-defangs-difficult-decis...
These articles about engineering process always put the responsibility solely in the implementing engineer's lap. Always more and more work to achieve JPL-level capability maturity, no matter your budget or headcount. Of course we want unit tests for every case, and verbose explanation in every atomic commit message, and architecture documents that are seldom read before they become stale. But make sure you also get…
I find writing text (preference: Markdown) and sprinkling it with visualizations (tables, graphviz...) to document stuff very useful and productive.
I don't see this as a burden but rather the opposite. A good portion of programming is not writing code, but thinking and communication. Using text as a direct output of this process helps in many areas. Mostly because we have a limited capability of keeping stuff in our heads at any given time.
A typical categorization of these documents would be:
- specification: describing the thing you build in detail
- todo-lists: organizing actions
- guides/instruction: describing usage of the thing you build in a accessible manner
- meeting & discussion protocols
The thing is: None of these things are extra or can be avoided. The only difference is whether you write them down or not.
The article describes something I would put into the fourth category, or maybe a fifth where you describe intent historically (like design documents).
I personally don't write design-documents or ADRs, nor have I ever seen them. But I assume that these become valuable in larger organizations and teams with a higher communication overhead. As soon you need to talk about these things over and over you want to write these down.
These articles about engineering process always put the responsibility solely in the implementing engineer's lap. Always more and more work to achieve JPL-level capability maturity, no matter your budget or headcount. Of course we want unit tests for every case, and verbose explanation in every atomic commit message, and architecture documents that are seldom read before they become stale. But make sure you also get…
> But make sure you also get your story points done for this sprint and meet your OKRs for this quarter. The problem here is the points aren't measuring quality, they are measuring a type of velocity that doesn't take into account quality if you aren't getting points for that work. Read: PMs often drive a timeline that accepts engineering risk, but not responsibility for that decision when it doesn't work.
These articles about engineering process always put the responsibility solely in the implementing engineer's lap. Always more and more work to achieve JPL-level capability maturity, no matter your budget or headcount. Of course we want unit tests for every case, and verbose explanation in every atomic commit message, and architecture documents that are seldom read before they become stale. But make sure you also get…
I can only directly relate to solo/small-team projects: I find writing text (preference: Markdown) and sprinkling it with visualizations (tables, graphviz...) to document stuff very useful and productive. I don't see this as a burden but rather the opposite. A good portion of programming is not writing code, but thinking and communication. Using text as a direct output of this process helps in many areas. Mostly beca…
This is the relevant part, to me. Can we do this documentation process JIT when someone asks about it? Maybe even convert the dialogue (in chat) or transcript of the conversation into the documentation.
Earlier quoted context omitted.
I can only directly relate to solo/small-team projects: I find writing text (preference: Markdown) and sprinkling it with visualizations (tables, graphviz...) to document stuff very useful and productive. I don't see this as a burden but rather the opposite. A good portion of programming is not writing code, but thinking and communication. Using text as a direct output of this process helps in many areas. Mostly beca…
> As soon you need to talk about these things over and over you want to write these down. This is the relevant part, to me. Can we do this documentation process JIT when someone asks about it? Maybe even convert the dialogue (in chat) or transcript of the conversation into the documentation.
When a collaborator or client talks to me or when I think about something, then I open a markdown file (first often just a notes.md) and just write in bullet points, and gradually organize it into categories.
I put these in version control as well since a while.
Thought experiment: if something is not worth writing down, is it worth discussing?
I'm personally a huge fan of the SPADE framework from Gokul Rajaram. First Round has a really good write-up on how to use it. [1] It serves both as an ADR and also a framework for making that decision in the first place, in one. I've introduced this at a few places I've worked and it's been very well received. [1] https://firstround.com/review/square-defangs-difficult-decis...