>None of the three can easily be captured in code, but are trivial to capture as documentation.
Posts like this frustrate me. Not because of what they ask, but because of what they incorrectly assume. They assume that documentation can provide enough context, and that human knowledge is not needed.
Every bit of written documentation can and will be misinterpreted. And perfect clarity is impossible. A well-written ADR does not eliminate all ambiguity, because there is too much cultural context around the writing of the ADR that attempting to read it from some other cultural vantage point leads to bad assumptions. We can find this basic lesson from reading law (2nd, 14th amendments to the constitution), history (what did happen after Muhammad died?), philosophy (what in the world is Plato's cave talking about?), or theology (how should we translate Ephesians 5:22-33 and what does that mean) outside its original context with other people.
Just writing things down and thinking an AI is going to later perfectly understand what the intent of the author is... patently ridiculous. I do not intend to dismiss the idea that we should probably document more, but the idea that the AI can just take our documentation and competently understand all the decisions represented in them is ludicrous.
Having worked at enterprise with 100+ engineers across multiple teams with complex reporting lines, I definitely agree with this. There's a lot of nuance behind decisions that docs simply can't capture. I mean in theory you can probably write every considerations that led you to make a certain decision, e.g.:
- I'm writing this service even though team X has built the same thing, because my team lead doesn't trust team X since the last time we depended on their service 3 years ago, they had a major downtime that screwed us up big time
- This service is using AWS Lambda simply because I think it's cool, despite the fact that the company has a dedicated team running k8s stack with argocd, argo rollouts, KEDA, etc for the entire company
- Service Y is written in this particular way because it's a service that is shared with another team that came from a company that was acquired, and they wouldn't use it unless we write it this particular way, and making the top execs happy is more important than dealing with a small tech debt (this is probably true)
But no one is going to write these in their RFC. But Sarah knows.
> They assume that documentation can provide enough context, and that human knowledge is not needed.
It's funny actually, because I fully agree with your reasoning. The only part were we differ is whether that's assumed, or even implied.
No documentation means running fully on tribal knowledge, or institutional knowledge if you prefer. Even if you capture your intent, imperfect and incomplete, in as little as 2 paragraphs, you'll get durable recorded memory, and intent you'll be able to reference. It does not eliminate ambiguity, but it adds framing, direction, and friction.
The examples are great, and they serve really well to prove another point that I intentionally left out: writing is not a one-shot activity. Documentation is living and should be treated as such. Unless it receives proper care continuously, it will wither and die. That could very well be the topic of a future post!
Thank you for reading and for providing thoughtful feedback!
I can’t tell from the text if the first paragraph of your response is meant to be ironic or tongue-in-cheek, but it certainly works that way.
It feels hard to recognize that you agree with me from the following paragraph of your post
> This is similar to asking Sarah why the team went for A over B, but without the imperfections of human memory, and available to agents as well. When an agent reads it, the decision isn’t an arbitrary historical fact - it’s the conclusion of an argument the agent can now evaluate and extend.
I definitely agree that human knowledge is imperfect, and that documentation is needed. But I just cannot get around the fact that the following sentence, out of context, can refer to football, American football, and basketball : ‘I passed to the center, and we scored’ and without more context, each of those can have multiple meanings even in each of the sports I named.
const hello = ‘world’
Is valid in so many programming languages that need more context.
No, the agents don’t ask Sarah, but maybe they should. And maybe I’m on this soap box because the thing is that I write internal line of business software and the technical stuff is easy. But when Sarah is the inside sales manager or the industrial engineer a continent away who speaks a different language, the reality of adequately capturing context for decisions that others have made that our software has to implement, and in a context rich enough for documentation to be succinct, is enough to make me frustrated with articles like yours that hand-wave that into ‘trivial to capture in documentation.’
I do agree with you both, but we need a wider view of what documentation means. I'm spending time this days reading the OpenBSD code and while the latter is really well written, I spent even more time reading the mailing list archives, the revision notes, the BSD4.4 book, some OS textbooks (Three Easy Pieces is great BTW), and various datasheets (Intel, USB,...). I would have a much easier time if I could find a dev to be my mentor and walk me through it.
All of this to say, tribal knowledge is valuable and rarely well captured. Even experts organize conferences and lectures instead of just sending each other papers. Written words is better than nothing, but knowledge is better transferred from the person that has it. If you lose that person, the only way forward is to train another one to replace it (either intentionally or not).
Pulling histograms from my dictation software, it's apparent that I speak for sixty minutes at a time multiple times a day at 200-350 wpm aggregate just... trying to communicate all the nuance about a tiny, _tiny_ subject area, for an agent to implement or write in plans/docs... and then despite the best efforts of both me and LLMs, that can be and usually still _is_ misinterpreted.
Whether bulk or terse, highly precise with words or highly nuanced in how it's communicated... I don't think any of that gets you to a place where the documentation is a substitute for asking the person.
People are trying to do this with meetings as well and certainly they help but code that's written plus meetings plus an architect like person yammering on endlessly about the nuance that went into it still is often not enough to capture the detail in earnest – and especially not in a way that won't be misinterpreted.
Perhaps if AI becomes truly superhuman in all of the relevant areas to the point that it makes the decisions just as well as the person in the chair... _then_ we might solve this by having it instantly pattern recognize the solution and the why, but until and unless we reach that day, I think what you're saying is very true.
People would often ask me why I would just read the code for a project rather than ask whoever wrote it. At the end of 30 minutes talking to someone, I may not have learned anything. Or I may have learned the wrong thing because they wrote it 3 years ago and forgot about it.
At the end of 30 minutes I either understand how the project works at a high level or know enough to know I'm not going to be improving anything with this project, ever.
>Every bit of written documentation can and will be misinterpreted.
Yes, humans (and human languages) are flawed and lossy.
>A well-written ADR does not eliminate all ambiguity,
True: no docs can ever eliminate all ambiguity (on a decent sized project at least).
But this entire argument seems to be "letting perfect be the enemy of the good". Documentation doesn't have to be perfect or 100% unambiguous to be useful.
I agree. But that usefulness can be deceptive, especially when one thinks enough context has been captured to prevent misunderstandings. An LLM (or human, to be clear) can easily
go down the wrong path from their own assumptions, and now you have three problems.
My main complaint is that articles like this lead people to think they they can avoid those three problems, without understanding why there are three.
I'm not sure CRDTs are actually the right answer here for your example of #2, Marco. A double-entry accounting system might actually be more ideal. In that case, what you are keeping in sync is the ledger, but depending on your use-case, that might actually be easier since you can treat them as a stream-of-data, and you would get the 'correct' answer of 100.
In this case, you would need two accounts, a credit and debit account, and then device A would write +20 to the credit account and -20 to the debit account, device B would write -20 to the credit account and +20 to the debit account, then using a HLC (or even not, depending on what your use-case is again), you get back to the 100 that seems from the description of the problem that it is the correct answer.
Obviously, if you are editing texts there are very different needs, but this as described is right in the wheelhouse of double-entry accounting.
That's not what a double-entry accounting system is for. If all you're doing is keeping track of one account/balance, then double-entry doesn't add anything. You might want to still implement it that way for future proofing though if you're implementing an accounting system.
The main thing to takeway is to store transactions like you mentioned (+20, -20). And in the simplest case, just apply all of them based on time.
You're not entirely wrong that double-entry accounting doesn't add much to keeping track of one balance. And the example provided in the article was very simple, just like mine was very simple. Transactions do help, but if you are trying to keep track of a balance and understanding how that balance is changing, double-entry accounting is helpful.
It's Wargaming who owns the IP and assets, and I doubt they release them, if they even have them. DrDeath or Mavor might have copies, but neither of them would likely release them.
Similarly, TA's source code never got released, and while Spring is great and ArmoredFish made good progress with RWE, I wish that code hadn't gotten lost either.
That’s one of Peter Watt’s Rifters trilogy, I think maybe the second one? Been a few years since I read them. I think it’s a biological neural net, not an Ai per se. Lots of big ideas in those books, but not a lot of optimism and some rough stuff.
I wonder if part of this has to do with the more complex, piecemeal nature of medical debt and these buybacks.
How I understand several of these groups (I'm not certain of the one in the article) do these debt purchases is that they purchase debt that has already been bundled together and resold. So when a person owes medical debt to a hospital, a doctor, a surgeon's practice, a pharmacy, etc, they may owe 15k in total, and these buybacks only cover one resold debt, they may have their hospital debt forgiven, for example, but still own 10k in total to the 3 or 4 other creditors.
Contrast that to a mortgage debt, for example, where paying off the mortgage relieves all anxiety around that debt, and I can see how the difference in complex, multi-creditor debt versus simpler, singular-creditor debt could help address the findings of this study.
Paying off your mortgage virtually eliminates your chances of ending up homeless, and absolutely drastically reduces those odds in the near term. This is at the foundational layer of Maslov's hierarchy of needs. I'd expect the impact on one's daily sense of well being to be massive.
Paying off your medical debt might improve your credit score over a long period of time, assuming you have other things going for you in that area. People who are worried about becoming homeless generally do not give a single shit about their credit scores. Having good credit one day is an aspirational thing for probably the majority of humans, closer to the 'optional' upper layer of Maslov's model.
I like how a foundational layer of maslov's hierarchy of needs is just something we shrug off as unattainable to many, but god forbid we discourage people from chasing profits at the expense of all else
When we both worked at an NGO in a mountainous desert country in a relatively peaceful period.
My advice is always, find the kind of thing that you want to be doing and then do it. In my case it was do something more meaningful with my life, in my now wife's case it was walk with the people in the country we were in. Our overall life aims were relatively close, and so one thing led to another.
I'm a Protestant, but that explanation of transubstantiation may be the popular understanding but is not the actual official doctrine of the Catholic Church. I'm not versed enough to explain it except by way of terrible analogy to software development - everyone knows what Agile is, but no one really knows what Agile is, and once you start to read the Agile Manifesto and think deeply, you realize that.
The Catholic Church (and the bible they started from) effectively say everything and its opposite, depending on which argument is convenient at any particular time. They've been debating (and training to debate) these subjects for more than a thousand years. The only official doctrine, in practice, is that they are Right at all times, no matter what the topic might be.
I wouldn't really characterize the Catholic Church's official doctrines that way or that flexibly, but again, I am a Protestant with a number of overall disagreements with them and less personal experience with them, and it is easy for me to read your post as someone with much more personal experience. And since HN isn't really the best place for extended religious discussions, if you are interested for any reason, my email is always open.
... “transubstantiation” refers to a change in which the substance of a thing—what it really is—changes, while its physical characteristics do not. Of course, this sort of change only occurs in the Eucharist, which, though it appears to remain bread and wine throughout the Mass, nevertheless truly becomes the flesh and blood of Jesus.
I took your using the word literally to mean you were saying that the physical characteristics changed, which is apparently not what you were saying.
I think this is a difference in language expectations, because when and where I grew up, some Protestants thought that Catholics believed either that the physical characteristics of the Eucharist changed during the blessing or consumption of the Eucharist, which your link seems to demonstrate to me that you are not agreeing with.
I'm a Protestant, but that explanation of transubstantiation may be the popular understanding but is not the actual official doctrine of the Catholic Church.
I was raised a Catholic, I believe doctrine changed at some time, maybe Vatican II? I remember being told as a child (a long time ago :) not to eat some time before communion.
Posts like this frustrate me. Not because of what they ask, but because of what they incorrectly assume. They assume that documentation can provide enough context, and that human knowledge is not needed.
Every bit of written documentation can and will be misinterpreted. And perfect clarity is impossible. A well-written ADR does not eliminate all ambiguity, because there is too much cultural context around the writing of the ADR that attempting to read it from some other cultural vantage point leads to bad assumptions. We can find this basic lesson from reading law (2nd, 14th amendments to the constitution), history (what did happen after Muhammad died?), philosophy (what in the world is Plato's cave talking about?), or theology (how should we translate Ephesians 5:22-33 and what does that mean) outside its original context with other people.
Just writing things down and thinking an AI is going to later perfectly understand what the intent of the author is... patently ridiculous. I do not intend to dismiss the idea that we should probably document more, but the idea that the AI can just take our documentation and competently understand all the decisions represented in them is ludicrous.