Hacker News Reader

Comment by kccqzy | Hacker News Reader

The reason people don't like to read the average design doc is because the average software engineer doesn't have enough writing skills to express the concept clearly and concisely without editing. The design doc becomes a mumble jumble of raw notes that nobody really understands except the author. And then people dread reading this kind of raw notes.

However, if someone tells that design doc writer that this is something like a term paper at school that is being graded, they can actually improve their writing by quite a bit by doing some editing. So the symptom is really the same as prototyping: people write draft-quality design docs and magically hope it to be a good quality piece of writing suitable for a wider audience. What they need is a few rounds of editing, just like when they write prototype code they need a few rounds of refactoring.

View on HN

As much as I get frustrated with GPT4's limitations when it comes to code, it's quite good at expanding detailed bullet points into solid design prose.

You still have to read it back and triple check it, as you would your own work, but you don't need all the time it takes to extensively expand it from draft.

Also, which it is in context it's quite good at documenting what needs to be done to test it.

I agree. I have used it for just that.

I apologize, but GPT4 is absolutely not good at doing that. It is good at adding filler words and a self-important writing style, but if what you have can be expressed in a bullet list, it will not be better expressed by adding fluff and puffery. I can see it being a big aid if you don't know English very well and need it to correct your grammar and word choice, but not much beyond that.

> It is good at adding filler words and a self-important writing style

That's what they said—design prose!

It's not adding fluff, it's expanding it to improve the readability. If it just added word fluff, it would be useless. What I do is write an intro paragraph into the context. Sometimes if I have a few lines of code, I'll paste that too. Then, paste my very terse bullets, then ask it: "Concisely expand the following bullets for readability"

i originally wanted to comment on this to disagree with you. then i sat and read your comment in full and realised i agree with you.

with a weird caveat …

if you don’t have an audience who is willing to read what you’ve edited, editing can be a partially pointless excercise.

last shop i was in i’d edit this stuff to glorious beauty. no-one else would ever read it. i tried presentations instead. didn’t help. i tried live sharing the doc in a meeting, no one cared.

but editing a design doc (or a big PR description or whatever) is always helpful for me as it is a process where i’m editing the problem/solution description without having to move code around.

i’ve done a few good refactors off the back of editing some text/diagrams.

lesson i learned: edit design stuff as if someone else will read it, but do the editing for myself (to learn something or clarify something about the problem/solution).

Why not get it read by a couple peers and iterate on their feedback? My writing is not great, but with the design docs I created, the first version is always terrible, not easily understandable mostly because of not listing all the assumptions whereas the third version almost always becomes something I would never be able to achieve myself. Over the years, I settled on 2 rounds of review. First to mostly add missing sections and rearchitect the design and the doc, second to mostly hone the explanation/details.

You have nice coworkers willing to read drafts. If your coworkers are busier (if they are more senior) they might not. Or they might read half a page and then stop because there isn't enough context and background information in the doc. Or they might read something and misunderstand it because of bad writing. I'm usually not the kind to waste other people's time like that.

Or, they won't say anything about it at all, because they (choose all that apply):

a) are not good communicators,

b) do not respect you,

c) are afraid to admit they don't understand (even if your doc is clearly shit),

d) do not care very much about the project.

In my experience, it’s usually (d), even if they are on the team.

Add to that engineers that don’t like/aren’t good at reading (at least in my time Zone) and you end up with people asking for stuff that is documented or even understanding the complete opposite of what was written.

its not just your time zone ;) and its not just engineers.

Reply on news.ycombinator.com