Comment by hermitcrab
17 hours ago
There is a (possibly apocryphal) story of cars being specified to understand a 100kmh air speed on the rear windscreen. 'Ridiculous, it can't reverse at more than 30kmh said the car designers' and ignored the spec. The first time new cars were transported on a train, all the rear windscreens blew in.
A long time ago I worked on a software product to try to record design decisions in the creation of long-lived artefacts, such as nuclear reactors. The idea being that engineers looking to make a change 20+ years later (when the original engineers had retired) would understand why something had been designed the way it had.
The project was not a success, despite some initial enthusiasm from some commercial sponsors. I think this was due to 2 main issues:
a) The software infrastructure of the days wasn't really up to it. This was just before wikis, intranets etc, which would have made everything a lot easier.
b) The engineers working on the design had no incentive to record the rationale of their decisions. It was extra work with no benefit for them (any benefit was by someone else, years down the line). In fact it could make it more likely for them to be held liable for a bad decision. And, in an age of cheap outsourcing, it could reduce their job security.
The second problem was by far the more important and I don't know how you get around it.
There's also a problem c)
c) Work tends to proceed in drafts/iterations, with earlier initial ideas refined and processed over time. You can record the reasons behind the initial ideas, but eventually those ideas become implicit background and new ideas are diffs against them. It's hard to make all of that explicit and keep it up to date.
You'd think something like wikis would help here because you can see the history. But eventually as you move around in the design space you can make moves that seem obvious but cut across multiple dimensions simultaneously. And it's hard to note something like that well in a wiki commit.
A long form lab notebook (or doc) is often useful here.
That is a good point. The more documentation there is, the harder it is to keep up to date. It also perhaps works against getting the best design, because nobody want to go back and change all the documentation. An argument for keeping the documentation fairly minimal, perhaps.
I like making good docs, and i appreciate good docs when i find it. I think alot can be done to make docs easier to maintain and more useful.
When approaching a large cryptic codebase, the intention and assumptions are usually more important than the details. And these are really quite simple to write down.
- Goals a Problems
- Constraints
- Chosen high level approach
- Relevant files, functions and resources.
- Future concerns
There is the worry about maintenence, but i think the history itself may be valuable.
If a design change happens, or a new major thing is added on-top, make a new document and timestamp it.
Over time this becomes a repository and history of the design and current state of the system.
Its harder to read and understand than a properly updated doc that is reflective of the current state, but its orders of magnitude better than not making docs because its annoying.
This problem can be solved by making documentation a natural side effect of the actual work.
One way is by recording video calls where the decisions are made with transcriptions which can be interpreted by LLMs.
Another is generating docs from tests.
Yet another is making a rule that answers to code review questions must be turned into code comments.
There's also a huge amount of untapped potential for turning conversations in slack into documentation.
The issue with wikis, etc. is yea, that it isnt a side effect of the work itself. It is work, and thankless work at that.
I love the story
You have to start thinking about product as the entire provenance chain, not just the end product. That means nobody gets paid for a working reactor. They only get paid for a working AND DOCUMENTED reactor.
Related, you have to make it benefit the current generation of engineers as well. Want to get your thing built? Deliver your designs in format X, which also happens to support long term reference.
None of this is easy… but it is actually possible to align incentives like this. You just have to do it from very high up, and with a very firm hand.
>[N]obody gets paid for a working reactor. They only get paid for a working AND DOCUMENTED reactor.
Doesn't really pass the market sniff test. Ceteris paribus, I'm pretty sure I'd pay at least ⅒ for a working but undocumented reactor in most situations.
>They only get paid for a working AND DOCUMENTED reactor.
Unfortunately that is rather easy to game. Especially in an age of LLMs.
Never mind LLMs.
I'll age myself here but about exactly 20 years ago I experienced exactly this. No LLM in sight.
Boss wanted to ensure we document something for our client. Cow-orker that didn't want to spend time writing boring documentation that might obsolete him (we were consultants working at a client) created an awesome looking table of contents structure and pages on the wiki. The first few entries had actual pages that had content in them. Of course they were also very "introductory" i.e. "naturally lean" on real content.
I checked every single page. Almost all of the rest of them were entirely empty pages.
He got through with this BS and it probably wasn't the first time (I was much more junior than him at the point) and it won't have been the last time. He got out of work he didn't want to do and nobody was the wiser until he was very far away.
LLMs just make this worse but they're definitely not required.
3 replies →
Is it though? I suppose it depends on how well things are reviewed after the fact - but I feel like there's a pretty big difference between a reactor and, say, a web app with poor documentation. I think if engineers wrote a bunch of documentation that was actually 90% blank (or nonsense) for a reactor, someone would notice.