Writing for Professional and Technical Audiences
pnewman.org
pnewman.org
Specifically:
// Know who you want to reach, what you need them to know, what context they have/don't have, and what you want them to do with the information you will convey.
This is basically everything but most people struggle (and actually don’t really try) to figure out what the other person has in their head and what buttons have to be pressed to take them from status quo to the new level of understanding. That’s a difficult amount of empathy to generate.
And then “what do I want them to do after reading this” requires vision and ownership. Most writing is “I’ll dump what I know and they can figure out what it means” which is horrible for the reader and jeopardizes the outcome.
So yeah the advice is “good” but the number of people who can actually figure out what they want someone to do and how to make them see the value of it is scant.
People read stuff and they don’t know even why and what for and disregard the context.
So lots of times it should be know what you read, know why you read it - if you don’t understand it, step back and check the context.
Fun part is that some writing is “I want people to hear me” and some is “I don’t want to repeat myself over and over again” - what I wrote will work with the latter one of course.
Unfortunately we don't have that technical writers, and I need to improve on this. I'd appreciate any and all recommendations.
I started my technical writer career ~11 years ago. We seemed to get much less respect back then. Gotta hand it to Stripe for really helping everyone see how much docs can contribute to a company's success. I still hear lots of other technical writers struggling with lack-of-respect though so maybe it depends on the company and maybe I'm just personally more sure of myself now that I've been at it for a while.
Also, thank you for respecting us!
> So we burn a lot of expensive engineering hours on writing bad-quality documents instead of hiring a few writers who could make sure things are in consistent style and filed correctly.
If you just need help with consistent style and filing correctly you might just need technical editors, not technical writers. I believe technical editors in general are a bit cheaper than technical writers, but I may be mistaken about that. Technical writers are much more involved in the overall creation and management of organizational knowledge. More on that after the next quote.
> I am 100% convinced this would be way cheaper and produce better quality.
We do consistently earn less than SWEs so yes, I think this is a pretty defensible argument to make. If you fall into the trap of thinking that you can offload all documentation work to technical writers, I would argue you might be making a very expensive mistake. The simple fact is that for any given domain there is a vast ocean of knowledge far bigger than the capacity of any technical writing team to document. We simply can't do it on our own, we always need the broader org contributing to the docs, too.
The more complicated fact is that docs are intricately connected to knowledge sharing in general. Teams think they're just offloading docs but what ends up happening is that their own knowledge-sharing tools / habits / processes atrophy. And the tragedy is that they possess knowledge not found anywhere else in the org. So everything gets less efficient.
There was a really interesting report that showed that high-quality docs correlate with above-average performance across an entire org. Unfortunately I don't think the report was presented compellingly but when you look at it in the light of "technical writers are shepherds of organizational knowledge" it makes a lot of sense and suggests the correlations are real: https://cloud.google.com/blog/products/devops-sre/deep-dive-...
So ironically, if you work with a senior technical writer, you probably won't actually find yourself writing less docs. We'll just make it less painful / more straightforward and you'll be more motivated to write docs because we keep hammering home how docs are connected to the greater mission :D
There is also the Leverage argument. A few hours spent on docu - if done right - will translate into hundreds (thousands? :) of hours saved by users AND by your own organisation's tech support.
Any dev who is not totally self-absorbed will "get it", if you can convince them that the downstream pipeline is there to translate their implicit knowledge into explicit, accessible knowledge.
Happy developers may or may not learn to assist & speed this process by cranking out some Markdown when the mood hits them.
If you write a document and only consider how you read it, it's fundamentally a document only designed to be read by you.
Or simulation. People have mistaken me for some kind of high-tier empath because my brain constantly (consciously or unconsciously) runs simulations on everything I do. Things I write are based on how I think it will be interpreted, not by whatever decides to come out of my brain. And things that other people are feeling are instantly understood because I can easily run a simulation of what that would feel like for me.
Maybe this happens because I'm autistic, maybe it happens because I have a dissociative disorder (DID), but whatever the case is, I definitely think it's interesting.
I think given the normative social allistic approach, the autistic person generally has a higher pressure to over develop their ability to compensate. Additionally, as this process uses the self as referent, it is less swayed by differences in the other and more prone to being activitated.
I believe that this is neither good nor bad, but the austistic person often suffers on people's assumption of being able to choose where their empathy is directed, and doubly due the effects of this trait. Things like strong, real, emotional connections to inanimate objects are an instance of this that can both cause suffering or joy, but socially can be a burden.
Thus I can fully believe that your approach is functional and high performing. And that others are often flawed by it. There's an innate integrity in it, because you put yourself directly "in the shit" when you do it. I wouldn't discount it as Machiavellian or as dissociative. Could it be that the dissociation is the cost, not the cause?
I don't know. I know that the dissociation mostly developed as an attempt to escape from reality... my theories on this range from "I just really liked computers" to "autism and ADHD ripped away so much control over my body that I don't even want to try to control my body anymore, I just want to be an internet creature". It doesn't have much to do with the simulations, it just makes them better since I have the ability to dissociate, I guess.
I will admit you're right, though, about me putting myself in the position of others. I can feel exactly what I would feel if I were there, in that exact moment. Because, in a way, I sometimes am. Since the mind is a complex thing and all that. I'm constantly in multiple places at once, not physically or spiritually, but mentally. It happens when I'm having multiple conversations at once, it happens when I'm context-switching between multiple situations at once, it happens when I'm having cognitive dissonance, and that's not even counting the situations where there are actual other personalities active at the same time because dissociative identity disorder really is a giant clusterfuck.
Facing difficulty happens to be a shortcut to empathy: you can imagine how others feel if you experience difficulty in many aspects of existence. You end up with a lot of parallel experiences to run simulations with.
These things combined create someone who can regularly act with empathy, or...an empathetic person!
Although spooking people by pretending to be an empath is fun.
I don't usually do that, but I have some very cold moments (the autism doesn't help).
Plus I'm really good at scaring people by being honest about how much I could be faking my emotions at any given moment.
- Do you take advantage of people, or do you think of ways to take advantage?
- Does your empathy turn off for no discernable reason?
- You tell others that you "could be" faking your emotions. Does your external body often display emotions that are different from your internal emotions?
Usually the latter, but I've done both. I don't really know which one I do typically though.
> Does your empathy turn off for no discernable reason?
Sometimes. It can depend on mood or it can turn off after a trigger (i.e. someone tells me something that they shouldn't have). I typically have really shitty opinions about things like wars and charities because I just really don't care even if I probably should.
(The shitty opinions are a shared trait with some people who have borderline personality disorder, but I don't know if I have that? Never been evaluated.)
> You tell others that you "could be" faking your emotions. Does your external body often display emotions that are different from your internal emotions?
This is honestly kind of a trick question because this will happen anyway because of autism. The body does not express me well. It's why I prefer online interaction, because at least there I can express my emotion. But in person it's very very difficult and takes actual intentional acting in order to display what I'm feeling.
This could also partly be attributed to the dissociative disorder.
Your world sounds chaotic. Making sense of chaos is never easy. Your strongly held beliefs may be a reflection of this: without them, there would be even more chaos. With them, you can eliminate extra conflict by avoiding people with different values.
This doesn't look like psychopathy. You're coping with extraordinary circumstances. How other people interpret what your body is doing is a choice they make. You're not lying if your body doesn't match social expectations of meaning. It's just doing what it wants regardless of your intention.
Also, be wary of mistaking coping mechanisms with a pathology.
They're conscious in the way that I can understand and explain them, but not in the way that I came up with the idea to do them. They just happened and I haven't done anything to change that. Part of that is ADHD's fault, because as soon as I started stimulants, I could just Decide that I didn't want my OCD anymore and it would go away. It's legitimately life-changing when that happens.
> Your world sounds chaotic.
Yeah, especially when there are multiple of me living multiple lives in parallel, and they interact in really weird ways ;-;
> Also, be wary of mistaking coping mechanisms with a pathology.
I know a lot about coping mechanisms. Basically everything I do is a coping mechanism. Even reading HN is a coping mechanism!
But I know I have the potential for dark things given the right "push", considering my entire DID system died and basically started over when one person left.
Thinking about dark things can be a side effect of being exposed to the dark parts of the world constantly. Suffering is inherently dark.
Systems are complex. It sounds like the DID system within your brain collapsed when a key part of the system stopped collaborating. That doesn't reflect on you: it would be like judging yourself for having an autoimmune condition, where your body is attacking itself. You don't have control over your autoimmune system.
I visualize it like this. There's the part of the brain that runs the DID system, and there's the part of the brain that culminates in your consciousness, which experiences the DID system. There's cross-talk between these systems because they use the same pathways.
Sorry, it was not someone within the system, it was someone external. It was heartbreak after a period of deep discomfort.
Don't worry, I spend a lot of my life trying to make sense of DID stuff. It's the curse of being autistic, I guess.
System dynamics are universal. :)
Kind of defeats the point of writing almost. Why this indifference?
We will get downvoted, of course, because omitting css is "cool" on HN.
I suppose, sure. But as the document ages the definition of “inclusive” will change, and some of the adaptations such as singular “they” can make writing less clear.
I use they as often as possible, but the writer needs to build their sentences with it in mind.
In technical writing you might say something like “The user will enter their password…”, where the pronoun “their” of course refers back to “the user”.
I've found that using "they" style does quite often make it harder to be clear, when you've got a sentence that's talking about both a person and some things.
Something like
"Then the operator must update all the rules. They must ensure that no bad things happen."
Does the "they" refer to the operator or the rules?
Of course you can always rephrase to make it clear again, but you're losing a certain amount of freedom of arrangement that you might have wanted to use for other purposes.
Paragraphs can "hide" key information that needs to be referenced more than once, because the info location is based on how words fit into the paragraph instead of by importance.
If a list is important enough that the reader will want to refer back to it later, then by all means format it _as a list_ in order to aid subsequent visual reacquisition.
I write a lot of instruction material for my undergrad students. They can be absolutely guaranteed to zone into whatever gap in the material I carelessly leave. In this way, most of my material undergoes plenty of iterations before it reaches its final form.
It took me too long realize I'd be saving time by spending more time adding meta sections to my documentation. "Devs will understand," I said, and boy was I sippin on my own juice.
Nobody. Asking for help would imply they don't know what's going on, which would be embarrassing, so they rebuild from scratch for the dozenth time, duplicating all the same mistakes, just in $HotNewThing.
The auditors like me, at least.
> Software development is all about knowledge and decision-making based on that knowledge, which in turn creates additional knowledge. The given problem, the decision that was made, the reason it was made that way, the facts that led to that decision, and the considered alternatives are all knowledge... each instruction typed in a programming language is a decision... Software design can last a long time. It can last long enough to forget about previous decisions made, as well as their contexts. It can last long enough for people to leave, taking with them their knowledge, and for new people to join, lacking knowledge. Knowledge is central to a design activity like software development. Most of the time this design activity is, for many good reasons, a team effort involving more than one person. Working together means making decisions together or making decisions based on someone else's knowledge. Something unique with software development is that the design involves not only people but also machines... Using a formal language like a programming language, we pass knowledge and decisions to a computer in a form it can understand. Having a computer understand source code is not the hard part... The hardest part is for other people to understand what has been done so that they can then do better and faster work. The greater the ambition, the more documentation becomes necessary to enable a cumulative process of knowledge management that scales beyond what fits in our heads. When our brains and memories are not enough, we need assistance from technologies such as writing, printing, and software to help remember and organize larger sets of knowledge.
Highly recommend reading the first chapter of the book. I'm not sold on the proposed solutions covered in the rest of the chapters.
In retrospect, providing guidance was never going to help because they never understood the "why" for what they were doing.
As a dev, one area I find I lack in is writing technical descriptions for less technical audiences. Does anyone have advice for that specific scenario?
e.g. explaining a bug and what’s needed to fix it, estimating level of effort for work, etc.
- Write the technical explanation first, then examine what concepts are required to reach the needed level of understanding.
- Avoid loading multiple new terms or concepts into one sentence.
- Introduce terms and their definitions as close together as possible.
- Style the text of defined terms to differentiate them visually, the way textbooks bold key words, so the terms are easy to reference.
- Make any introductory text easy to reference multiple times.
- Lists of words and phrases are easier to reference if formatted as a list, not a sentence.
- Lists with multiple dimensions, such as a list of terms and definitions, are easier to reference if formatted as a table.