3 ms·
I really love this idea in theory, and I believe that for some system, specially mature ones, it may work well. I see good documentation as a super power; it em
by p-o 2y ago
I really love this idea in theory, and I believe that for some system, specially mature ones, it may work well. I see good documentation as a super power; it empowers readers and motivate people to understand more about the system without being caught in the weeds of reading the source.
The source has baggages, and the intent of every single function calls is not always evident. Writing documentation up-front can help direct the source, but this is a tug-of-war environment. Each affect the other in its own ways.
And for that reason, documentation driven development can be a real drag. You start writing documentation with the best intentions, everything works great for this first release. But 2 months down the road you need to modify something and it has a ripple effect on many of the things you documented. It's a non-negligible cost.
I've been working on this open-source tool(https://github.com/pier-oliviert/sequencer https://github.com/pier-oliviert/sequencer) and I've spent a lot of time on the documentation. And what I described above happened. I wanted to make a not-too-big change, and it required me to rewrite 30% of the documentation. I still love the documentation aspect of it, but it definitively has a higher cost than tests, in my experience.
- lowercased 2y agoWould be interesting to see what impact some sort of llm system might be able to have on this approach. Making some changes in one area of the documentation, then having a system indicate some other likely areas of impact which you might not have considered, seems like it would be useful.
- p-o 2y agoI never thought of that problem this way, but it sounds very cool. I imagine a sort of conversation between the LLM and the author. - LLM: Did you mean to change A to B? - Author: Yes, but [more nuanced information] - LLM: Ah ok, here's the documentation updated: [Doc]
- kevindamm 2y agoIf the model can reflect the existing documentation that well, w.r.t. changes in code, you may as well use the LLM as the documentation by fine tuning it with boilerplate/initial docs and have it generate the future documentation based on a context of just the code. My attempts at this (DDD) involve choosing system components or protocol/API layer dependencies such that they can generate the documentation when they generate the client-lib and server interface code. Isn't always possible, and doesn't cover everything. Having a comment-doc pipeline also helps but sometimes that just adds more trees to occlude the forest. This way the documentation doesn't lead the code too much (I'd rather see deprecated warnings than Not Yet Implemented errors). Good team communication and a solid codelab for new members can go a really long way, too.
- kaycebasques 2y agoThis is basically a holy grail for us technical writers. I know quite a few people working on it.
- kaycebasques 2y ago> it has a ripple effect on many of the things you documented Welcome to the world of technical writers :D (In other words, I'm suggesting that this is always the case and it's not something peculiar to DDD. I would argue that DDD has just made you more sensitive to what we go through every day. But yes, if you try to create a final doc and the features aren't stable, you're going to have some wasteful churn.)