41–50 of 64 posts
They could have included some nice examples from GitHub themselves in this blog article.
At work we have a decent PR template that prompts people to provide context, alternatives considered, and underlying reasons for the change, which works pretty well. I’m trying about how or whether ADRs would function better, or if they would operate at a slightly higher level of change (i.e. for work that extends across multiple PRs).
I’d be interested in thoughts or experience people have, especially in medium or larger organizations.
This is far from the first time I've evangelized this paper here on HN... but I think the ideas of the OP and the Naur paper "Programming as Theory Building" have a high degree of overlap. Indeed, at some level, the Naur paper deals with identifying the problem while the OP deals with practices to bridge the knowledge gap identified in the paper. http://pages.cs.wisc.edu/~remzi/Naur.pdf
Thanks for the recommendation! Already enjoying this!
- https://pastebin.com/raw/WwXKAGnW
- https://gist.github.com/onlurking/fc5c81d18cfce9ff81bc968a7f...
Earlier quoted context omitted.
so what would the experience be for someone new joining the project, particular if you have many repositories? having to search across numerous repositories? In practice I've found this (source control commit messages as ADR's) doesn't work. Unless I have mistaken what you have said? I just keep a repository for ADR's, which can then be published to a wiki or else where.
In that situation, I think the best layout is: - your centralised wiki lists all the repositories and explains what they’re for; - each repository has a detailed commit history, allowing you to understand the thinking behind each line of code. Edit to add: you can search across multiple repos with Github’s “search in organization” feature, and it actually works very well. I usually find that much more useful than sea…
Ch ch ch changes
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…
I would agree that ADRs are not really necessary if you work alone. Maybe not even within a team if it stable over a long time. Where ADRs are helpful is when many teams cooperate and if people come and go. The reviews happen implicitly because the decision is discussed among many people.
Not all our designs and decisions panned out ofc, but just having the articles already helped a ton getting through that DD and it really helps give new starts a much better feeling for the code base and where it came from
The design process will ideally happen asynchronously, as comments posted in the issue.
That way, a truthful trail of diverse considerations will be left in written form.
Contrariwise, ADRs can be too written excessively after-the-fact, by a single person. I have seen them degenerate into bureaucracy ("we designed X because X seemed the best option"... how informative).
Earlier quoted context omitted.
> 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.
I just started to write anything down basically... 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?
The “whys” here all sound sensible, but I’d be even more interested in _how_ people are implementing a process around ADRs, where you’re keeping them, etc. At work we have a decent PR template that prompts people to provide context, alternatives considered, and underlying reasons for the change, which works pretty well. I’m trying about how or whether ADRs would function better, or if they would operate at a slightly…
Pro: Wysiwyg is great for editing it live in meetings, plugins like Gliffy are nice for diagrams, integration with Jira, accessible with a simple link.
Con: Not good enough for long term archival, so we export them to pdf regularly, wiki has no atomic commits.
We have a regular meeting where the team architects together discuss and ultimately approve these documents.
1. How do I articulate the criteria for when a decision should have an ADR?
2. I always see ADRs in the context of recording what was decided, but I’d like them to be raised more like requests for comments (RFCs) for a week or two first, particularly in cases where there may be impacts on other systems, security or data protection implications. Are ADRs often used this way, or should I be looking at something else?
Any advice?