4 ms·
We have debated this a lot in our organization. We are tired of seeing low effort Tech docs that puts the onus on the reader than the writer. I think that the w
by murlax 19d ago
We have debated this a lot in our organization. We are tired of seeing low effort Tech docs that puts the onus on the reader than the writer. I think that the writer should spend at least an order of magnitude of time more than the reader. If not, then the design doc can just be the LLM prompt that generated the document.
I have actually resorted back to hand crafting TDDs and focusing on 1-2 page docs. It is a great way to organize my thoughts and create a shared mind space among other engineers. My 2 cents.
- luc_ 19d agoCan you summarize your thoughts into a single prompt that, with the context of the codebase, gets expanded to something that makes sense?
- 0xbadcafebee 19d agoI agree that we should basically be requiring hand-written-only design docs, because it should force people to make sure they know what they're getting someone else to read. But there's two problems I run into: 1) A lot of people who write design docs, RFCs, etc, don't write them well. I end up needing to get them on a call and explain their entire idea to me because it's the only way to pull the details out of them. 2) Regardless of how much I write by hand, I still have engineers who are so incredibly lazy that they just don't read the docs at all. They can't be arsed. So I have to get on a call and basically explain the whole doc to them. This is starting to lead me back to what other people hate: meat puppeting. Telling Claude my idea, Claude writes it up, and I ask that engineer to ask their Claude to read my Claude output and summarize it for them. I really want a better solution, but our engineering management is almost nonexistent, so nobody does anything they don't feel like doing.