It’s reasonable and even good advice but the hard parts remain the hard parts.
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.
That’s very fair. I would call what you described as “reference” and it may have the benefit of an audience that has an explicit question that you already know they are asking. Agree that’s a little easier to “nail”
I wish we would give tech writers and generally the art of writing more respect. My company is in the medical field so we have to produce a ton of documentation. Turns out most developers aren't good writers, don't really want to write and are very slow at writing. 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. I am 100% convinced this would be way cheaper and produce better quality.
> I wish we would give tech writers and generally the art of writing more respect.
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
> you'll be more motivated to write docs because we keep hammering home how docs are connected to the greater mission
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.
I currently work as a dev but have a more scientific background, and that background is leaking into my writing, so much so that I have been told that my documents are too abstract and "science-y". My more technical audience - principals + - are fine with it, but others struggle a lot.
Unfortunately we don't have that technical writers, and I need to improve on this. I'd appreciate any and all recommendations.
All of this is basically just empathy. "If I were in $position, how would I handle reading this". Answer that question for every value of $position your readers could represent and you won't be far off.
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.
My familiarity is that autistic people often experience heightened empathy not on the simulation/experiential divide but a difference in self other relations. That is, the autistic approach to intentionality places themselves verbatim in the position of the other, rather than the allistic which replaces themselves with the other.
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?
> 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.
Being able to simulate other people's experiences in your mind is a base skill required for empathy.
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.
A few more questions probing the source of the psychopath belief:
- 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?
> Do you take advantage of people, or do you think of ways to take advantage?
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.
You describe a lot of processes that aren't fully conscious or intentional, whereas an average person would have control over that piece of consciousness.
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.
Living in a world of chaos means you have more opportunities to see potential darkness within yourself than the average person.
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.
The person existed external to the DID system, but your internal system came to depend on their continued existence in your life. The DID system changed how it worked to adapt to the existence of this person. When that person left (stopped collaborating), the internal systems that depended on that person's existence collapsed.
The styling is a bit ... lacking. Anybody that cares about their reader, would not expose them to this brutalist styling experience. It's basically unreadable. Not just a little bit. It's really hard to read on a normal laptop screen.
Kind of defeats the point of writing almost. Why this indifference?
Yes. I came here to comment that the author forgot the most important topic: legibility. I read exclusively on mobile and my days are filled with frustration. To save time and make my reading sessions more productive I had to self-impose a hard rule: to just abandon unreadable websites. Perhaps we need to coin something like “TLDR” but for legibility and accessibility, to warn authors that they should refactor their web experience. Maybe “NLDR” — Not Legible, Didn’t Read?
> Read up on inclusive language and make sure you aren't including outdated terms.
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.
Can you give an example where it would be confusing? I know it is controversial, but to me it seems very convenient when referring to an unspecific person.
Over the years I've done a fair amount of reworking documents from "he or she" style to "they" style.
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.
As a matter of language use only, the phrase "They are coming over to my house later". Should I expect one person, or multiple people? Should I go out and grab a 6-pack of beer for my visitor(s) or a case? Easily clarified, and I'm happy to use people's preferred pronouns, but let's not pretend there isn't the loss of precision there.
A piece of text does not use they/he/she without first establishing the noun that these will reference. The problem you are referring to does not happen if you write correctly.
Pronouns refer back to some previous noun phrase. Saying “she is coming over to my house later” would also be a weird and confusing thing to say without first establishing who you are talking about.
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”.
It's not mentioned, but the author makes use of it: bullet points for clarity.
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.
This is an important observation. Lists embedded in looong sentences deformatted into text paragraphs lead to the dreaded MEGO syndrome.
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.
Solid advice that exemplifies the principles which it describes.
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.
I get flack for being descriptive, citing prior policy, and putting things on timelines when everyone is in the know, but the second they move on to the next crisis or a re-org happens and no one knows how the fuck anything is working, guess who they come to?
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.
Here's a quote from a book called Living Documentation that I think will resonate a lot with you. Long but worth it:
> 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.
One of the worst projects I ever consulted on was the one where they couldn't give sound reasoning for many of the key decisions they made early on, before I was brought in board to add some expertise in the tech stack they chose.
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.
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.