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.

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?

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.

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

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.

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.).

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. Don't confuse sales with marketing. Let's engineers do engineering communication. Details matter, sure. But the big modalities matter too. It's simply NOT a blur between the three

* Good communication requires one to know who 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

* There's an important extreme of the previous point that needs emphasis. Too many ``communicators" cannot tell the difference between a piece of communication for ``some other", and one's personal diary. I call this diary communication (or diary code). My diary is for me; there is no audience. It can be terse, sweet, staggered, pithy because I know all the players, context, back story. That data is elided from my diary. Hell, maybe it's even right in places. But do not labor under the insane delusion it forms the basis of information for others to build off. You cannot build a team with a bunch of diary nonsense.

* Do not communicate everything you know/think. It's called communication not a data dump. Have some game; you gotta have taste. Try this: overload on the first date with a smart, beautiful lady ... see how that goes ... see if she ever wants to waste time on you again

* Avoid owl talk, jargon. If I cannot work out a reason why I'm faced with dealing with bunch jargon I assume the speaker is deficient, is hiding something, or is an empty hat passively repeating whatever he read 10 minutes ago. It's never a good look.

* Read the room: if you blab on for 10 minutes and nobody has questions ... you blew it. You're another brick in wall, and another reason why people hate meetings

* If you publish ``communication" on the web for God's sake do not atomize it by placing each electron of info from the whole in 62 quadrillion places connected by html links. F that. Stay one book/single-volume/whole-unit. The web has almost single-handedly insured we can only learn about electron sized pieces of info without every realizing there's atoms, molecules, matter up to Shakespeare/Newton i.e. the good stuff. I want the good stuff. I resent having to struggle through a maze of BS to get it

* Some companies are especially clueless. Some companies suck bad. Have you ever had to deal with Mellanox? Wow! It's a shame