Discussion
So, what does #LiterateDevelopment look like, now?
Well, it bears repeating that the *literate* part (which Robert C Martin would still call "code") should be committed to trunk. It needs to describe implementation, maintenance, testing, deployment, and all the same dimensions of utility documentation has always served.
But now, it needs to be on trunk, not in a separate repo or wiki.
Is that awkward? But we have the tools and many ways to do it, and we're just getting started.
Caveats!
Primarily:
Docs are code!
Tickets. Diagrams. The roadmap. All the project management stuff defines the software. With Claude (I have yet to branch out, but believe me, it's coming) I have begun committing project management documentation to trunk. (Rename master to trunk, you colonialist.)
*Everything* I generate with an LLM is based on committed English documentation.
This is #LiterateDevelopment! Thank you, Donald Knuth and your contemporaries. And thank you Robert C Martin.
I very much appreciate @nlnet 's balanced approach to the conversation on code generation.
( https://nlnet.nl/foundation/policies/generativeAI/archive/feedback/ )
The human-agent history is as important as the SCM log.
However, the human-agent history is bare. For maintainable agent-mediated code bases, developers need, quite literally, comprehensive specs to repeatedly reference and verify.
This is not #vibeCoding.
Actually, I want to pit #LiterateDevelopment against #VibeCoding directly.
Clean code has *always* been literate. That means a dev with the skills to maintain the code base should be able to read the code. The *only* valid argument against documentation has been that the code is self-documenting. Okay, maybe with a high level language and enough care, the docs can be fairly spare. I would still argue for documentation, but I have lost some of those arguments.
…
… #LiterateDevelopment vs #VibeCoding. FIGHT!
Also, people have *always* vibe coded!
You don't have to be around long to find code that makes you wonder … until you realize the author just didn't care.
Vibe coding is the engine driving so many startups toward their exit. If the goal is to exit, not maintain, it just has to "work" until the ink on the sale dries.
Slop code has always been. #AI has merely lowered the bar for its creation.
These people are not writing literature.
@travisfw oh my yes. My first programming job out of college was working at a consulting firm that VCs would send their newly-funded startups to so that we could clean up their brittle, slop code and make it possible to build on top of
So, what does #LiterateDevelopment look like, now?
Well, it bears repeating that the *literate* part (which Robert C Martin would still call "code") should be committed to trunk. It needs to describe implementation, maintenance, testing, deployment, and all the same dimensions of utility documentation has always served.
But now, it needs to be on trunk, not in a separate repo or wiki.
Is that awkward? But we have the tools and many ways to do it, and we're just getting started.
This is what I am learning now. How best to maintain project management docs, specifications, tickets, and so on, on trunk.
I started out putting it in a separate branch and committing generated code to its own branch, and merging. I thought my prompting and writing was just for me, or at least, not what people would want to see.
#LiterateDevelopment #CleanCode
I have realized the error of my ways. The docs are the code. The English is the important part, now.
How are you doing it?
