Let's Talk About Writing in Tech(gmoniava.com)
gmoniava.com
Let's Talk About Writing in Tech
https://www.gmoniava.com/blog/lets-talk-about-writing-in-tech
23 comments
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.
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.
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.
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.
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.
I agree, writing is a skill.
My point was that when it comes to documentation, other skills are primary.
So--I wouldn't advise developers/writers looking to improve documentation to 'become better writers', I'd advise them to focus first on the other other skills, because without them 'good writing' in documentation is worthless. Put another way, the ultimate measure of good documentation is: how well it helps the user accomplish their 'jobs to be done'.
So--I wouldn't advise developers/writers looking to improve documentation to 'become better writers', I'd advise them to focus first on the other other skills, because without them 'good writing' in documentation is worthless. Put another way, the ultimate measure of good documentation is: how well it helps the user accomplish their 'jobs to be done'.
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?
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?
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.
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.
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.
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.
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.).
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.).
Then they weren't doing their job well.
Digital Ocean?
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.
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'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.
I'd take poor grammar and interesting ideas over clear grammar devoid of real content any day of the week.
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/samplep...
Microsoft: https://learn.microsoft.com/en-us/style-guide/welcome/
Red Hat: https://stylepedia.net/style/
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/
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.
>Undoubtedly a big opportunity area for LLMs
Are you kidding me? This is the laziest, campiest, knee-jerk point I've run into in quite sometime.
I expect, as my co-workers expect of me, to learn and improve. Writing is a core part of engineering, and management.
I'd have some choice words for my co-worker (or vice-versa) if we just gave up and "ChatGpt'd our way to the top."
Are you kidding me? This is the laziest, campiest, knee-jerk point I've run into in quite sometime.
I expect, as my co-workers expect of me, to learn and improve. Writing is a core part of engineering, and management.
I'd have some choice words for my co-worker (or vice-versa) if we just gave up and "ChatGpt'd our way to the top."
My goal is to be better than the LLM. :) As of now, it's a pretty low bar, I think.
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.
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'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.
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.
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
* 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
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
[1] “When I was your age, television was called books.” The Princess Bride
Agree! Definitely. Always. All day long, and twice on Sunday. Effective communication is both about the parts (details) ---AND--- composing the parts into an integrated whole. You gotta have both.
So don't screw it up by lapsing into atomic incremental update mode where I fix this one ticket, an error, of tell you about some new bit of info then communicate it by writing a new page cross-linking other stuff. Integrate the update.
So don't screw it up by lapsing into atomic incremental update mode where I fix this one ticket, an error, of tell you about some new bit of info then communicate it by writing a new page cross-linking other stuff. Integrate the update.
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