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 · 2h ago
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.
jamesgill · 5h ago
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.
jmye · 1h ago
Even if you believe that writing is the “easy” part, most developers/technical people are still woefully bad at it.
I would say that it is, generally, not easy to describe complex things simply, and people who are naturally adept at using language often underestimate the difficulty.
theletterf · 5h ago
The posts has a promising start, then abruptly ends.
They also need to hire technical writers. Did the author know they exist?
tolerance · 5h ago
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 · 3h ago
I see in your review that you also mention Docs for Developers, which gets a +1 from me as a documentarian :)
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.
crosser · 4h ago
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.).
tolerance · 5h ago
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 · 2h ago
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.
x2tyfi · 6h ago
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 · 5h ago
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.
CharlesW · 5h ago
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:
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.
beej71 · 3h ago
My goal is to be better than the LLM. :) As of now, it's a pretty low bar, I think.
scrubs · 2h ago
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
vincent-manis · 4m ago
The “atomization” issue is one of my biggest bugbears, which I often comment on here. If your project's documentation is a website with many small documents all linked together in multiple ways, don't expect me to spend time trying to sort it all out. I recognize that some people are hyperlink-happy, but my way of learning was influenced by an obsolete technology called “books”[1], which provide a linear path, so later topics can build on earlier ones. This is very basic pedagogy, which so many documentation practices ignore.
[1] “When I was your age, television was called books.” The Princess Bride
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
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.
I would say that it is, generally, not easy to describe complex things simply, and people who are naturally adept at using language often underestimate the difficulty.
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?
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.
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.
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.).
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 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.
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.
I'd take poor grammar and interesting ideas over clear grammar devoid of real content any day of the week.
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/samplep...
Microsoft: https://learn.microsoft.com/en-us/style-guide/welcome/
Red Hat: https://stylepedia.net/style/
* 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
[1] “When I was your age, television was called books.” The Princess Bride