[HN Gopher] Let's Talk About Writing in Tech
___________________________________________________________________
Let's Talk About Writing in Tech
Author : gmoniava
Score : 30 points
Date : 2025-06-22 18:37 UTC (4 hours ago)
(HTM) web link (www.gmoniava.com)
(TXT) w3m dump (www.gmoniava.com)
| x2tyfi wrote:
| Undoubtedly a big opportunity area for LLMs. I've recently
| observed engineers deliver LLM-generated (or iterated) docs that
| blow away any technical writing they had done in the past.
|
| Network Engineering design docs can be somewhat formulaic
| structurally, making the LLMs job simpler. I imagine in the near
| future we'll just ask them to follow doc templates or reference
| other designs within a RAG system to ensure there aren't gaps in
| the doc, etc.
| nrclark wrote:
| I'm not sure about that. For whatever reason, I've noticed that
| my brain has a hard time holding onto ideas from LLM-written
| documentation. Maybe because LLMs generate the mathematically
| lowest-energy thing that they can.
|
| I'd take poor grammar and interesting ideas over clear grammar
| devoid of real content any day of the week.
| x2tyfi wrote:
| That's understandable - the rule of "garbage in, garbage out"
| certainly still applies. I find that many engineers are
| capable of gathering the right requirements and content, but
| struggle with the polish/finish that makes docs more
| consumable - where LLMs can shine.
| CharlesW wrote:
| Assuming that your ability to remember the content isn't a
| result of differences in the substance of the content, in my
| experience the stylistic issue can be addressed with
| thoughtful training/prompting and _lots_ of Do /Don't
| examples.
|
| It helps if your technical writers already adhere to a
| voice/tone guide, which can be pretty easily adapted/extended
| for automated documentation generation. If one doesn't exist,
| you'll definitely want to create that first. Some good
| examples:
|
| Google: https://developers.google.com/style
|
| IBM: https://ptgmedia.pearsoncmg.com/images/9780132101301/sam
| plep...
|
| Microsoft: https://learn.microsoft.com/en-us/style-
| guide/welcome/
|
| Red Hat: https://stylepedia.net/style/
| beej71 wrote:
| My goal is to be better than the LLM. :) As of now, it's a
| pretty low bar, I think.
| theletterf wrote:
| The posts has a promising start, then abruptly ends.
|
| Yes, developers need to improve writing skills. A good book on
| the matter is Chris Ward's Technical Writing for Software
| Developers, which I reviewed here: https://passo.uno/review-
| technical-writing-software-develope...
|
| They also need to hire technical writers. Did the author know
| they exist?
| tolerance wrote:
| You know, I really want to thank you for referring a book and
| including a review of it, especially your own.
|
| More on topic, I'm under the impression that this is a budding
| idea of the author's, at least as budding as a thought willing
| to be made public can be without being totally picked a part by
| the crowd here.
|
| So yeah, he needs to read that book and post a review of it
| next. Keep the butter churning.
| spondylosaurus wrote:
| I see in your review that you also mention Docs for Developers,
| which gets a +1 from me as a documentarian :)
|
| https://docsfordevelopers.com/
|
| Although truthfully I'm not picky. If you're a developer and
| make any conscious attempt to hone your writing skills, I will
| love you forever and prioritize your Jira tickets accordingly.
| jamesgill wrote:
| As someone who spent a long time in technical writing, and wrote
| a decent-selling book about getting started as a tech writer,
| here's my thought: The problems with software
| documentation/tutorials/etc. rarely have anything to do with
| writing skill--because the biggest challenge is not writing, it's
| how to analyze and understand the audience and design what
| 'documentation' they need to get the job done. Separate skill(s),
| unrelated to writing. "Writing", in fact, is the easy part. Think
| of it this way: you can write the most beautiful, elegant,
| correct JavaScript that's ever been written: and it can be
| utterly useless. Beautiful code is good, but that's not the goal
| or the focus.
| mdaniel wrote:
| My contribution to this debate is that it isn't a developer
| problem it's a "beginner's mind" problem, which I personally
| characterize as "empathy"
|
| Can one recall what it was like 15 minutes ago when you didn't
| know the answer, and how would you have changed the situation to
| foster the pathway that would have squared up the product's model
| with your mental model. No matter the product: library, webpage,
| physical tool, bureaucratic process, etc. If a human(s) made it,
| then managing the assumptions is a grade-A problem that requires
| managing throughout its lifecycle
|
| Developers love to complain about bad requirements, but
| documentation is where one gets to provide the requirements to
| the reader, thus, is an empathy management exercise
| spondylosaurus wrote:
| People also call it "the curse of knowledge," and yeah, being
| able to empathize with the non-expert is both an ongoing effort
| and a learned skill.
|
| A lot of my job as a tech writer is basically acting as a shock
| absorber for user frustration in that regard, because when I
| need info from devs it's a constant struggle to get them to
| explain what they built--they often give descriptions that
| don't make sense unless you're already familiar with whatever
| they're talking about, which sort of defeats the purpose of a
| description. So I have to do all the teeth-pulling up front,
| and eventually get the necessary info, and then present that
| info in a way that actually makes sense to users.
| tolerance wrote:
| I have a hunch that technical documentation may be one form of
| writing that LLMs won't be able to really help with beyond the
| mundane grammatical/structural advantages that it affords to any
| other form of writing.
|
| AI is utterly swaggerless and I have a notion that a lot of what
| people enjoy from technical writing is the vibe they get from the
| writing; as much as the instruction.
| spondylosaurus wrote:
| I'm a little biased, but as a tech writer who doesn't think
| they'll be made obsolete by swaggerless LLMs any time soon I
| strongly agree. If you've written enough docs and sufficiently
| internalized all the stylistic best practices, putting words in
| order is the easy part; I could do that in my sleep. But
| technical writing is like 20% writing and 80% research, fact-
| checking, QA, diplomacy, and searching for (metaphorical)
| unexploded ordinances that could blow up in users' faces if you
| don't direct them down the right path.
|
| I would guess some of the vibes you mention come down to actual
| writing style, which I have plenty of opinions on (some of them
| controversial among my fellow writers!), but I think there's
| another subtler aspect of reading something that really
| anticipates your needs as a user and feeling like you're in
| good hands. It's something I don't always nail, but I always
| notice when I read docs that do.
| crosser wrote:
| I once worked for an organization known for providing good
| documentation.
|
| This is how it worked:
|
| They had a documentation-writing branch. And you (developer) knew
| that if you don't write documentation, they will. And then if
| will cost you _more_ time and frustration to review and correct
| what they wrote than to write it yourself and give to them.
|
| So you did write it (and they proofread it, corrected grammar
| etc.).
| scrubs wrote:
| Critical subject. In engineering
|
| * do not assign writing or communication tasks to hackers, nerds,
| techies, dorks Assign to engineers
|
| * periodically retrain engineers to write
|
| * let sales do sales. Let's engineers do engineering
|
| * good communication requires one to know wjo the audience is and
| what they care about and how/where it intersects with what one
| knows. If you're confused, sit this one out
|
| * do not communicate every thing you know/think. It's
| communication not a data dump. Have some taste and know what's
| what. Go ahead and overload on first date ... see how that goes.
|
| * avoid owl talk, jargon. If I cannot work out a reason why I'm
| faced with dealing with jargon I assume the speaker is deficient,
| hiding something, or is just passively repeating what he read
| elsewhere. Its not a good look
|
| * if you publish stuff on the web for God's sake do not atomize
| it by placing each electron of info ofthe whole thing in 62
| million places connected by html links. F that. Dude,
| book/single-volume.
|
| * some companies are especially clueless. Have you ever had to
| deal with mellanox on the web? Good engineers don't let engineers
| accidently copy bad stuff. Keep your friends on the good side
___________________________________________________________________
(page generated 2025-06-22 23:01 UTC)