[HN Gopher] Writing for Professional and Technical Audiences
___________________________________________________________________
Writing for Professional and Technical Audiences
Author : luu
Score : 139 points
Date : 2023-10-27 23:26 UTC (23 hours ago)
(HTM) web link (pnewman.org)
(TXT) w3m dump (pnewman.org)
| Daub wrote:
| 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.
| leetrout wrote:
| And their ability to not just zero in on gaps but creatively
| twist things to their favor.
| cyrnel wrote:
| Good advice! I recommend this book, especially chapters 1 and 9:
| https://archive.org/details/technicalcommuni0000ande_y9j8/pa...
| GinsengJar wrote:
| Great read, solid principles.
|
| 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.
| washadjeffmad wrote:
| 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.
|
| The auditors like me, at least.
| kaycebasques wrote:
| 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.
| cratermoon wrote:
| 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.
| elicksaur wrote:
| All good advice!
|
| 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.
| mgaunard wrote:
| Just make sure you explain every technical term or acronym
| before you use it.
| growingkittens wrote:
| Depending on the scenario, here are some ideas:
|
| - 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.
| growingkittens wrote:
| 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.
| SoftTalker wrote:
| > 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.
| distortionfield wrote:
| If clarity is the problem then one should use an actual name
| instead of a pronoun anyway.
| bazoom42 wrote:
| 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.
| thejteam wrote:
| It is very convienent. It gets unclear when people try to
| substitute it 1-1 for he or she in situations when the number
| of people is unknown.
|
| I use they as often as possible, but the writer needs to
| build their sentences with it in mind.
| fragmede wrote:
| 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.
| abdullahkhalids wrote:
| 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.
| fragmede wrote:
| You are quite right. Unfortunately, my life puts me in
| the position of interacting with people who's writing,
| especially via SMS, is often incorrect.
| bazoom42 wrote:
| 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".
| mjw1007 wrote:
| 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.
| bazoom42 wrote:
| Yeah, I can see how this can be confusing.
| adhesive_wombat wrote:
| 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.
| LoganDark wrote:
| > All of this is basically just empathy.
|
| 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.
| Honga wrote:
| 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?
| growingkittens wrote:
| 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.
| LoganDark wrote:
| Except I'm more regularly a psychopath. I only care about
| the feelings of those who are close to me.
| growingkittens wrote:
| What leads you to characterize yourself as a psychopath?
| LoganDark wrote:
| The fact that my "empathy" can turn off extremely easy
| and I can completely stop caring about someone in an
| instant. Or take advantage of them.
|
| 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.
| growingkittens wrote:
| 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?
| LoganDark wrote:
| > 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.
| growingkittens wrote:
| 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.
| LoganDark wrote:
| > aren't fully conscious
|
| They're conscious in the way that I can understand and
| explain them, but not in the way that I chose 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.
| jillesvangurp wrote:
| 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?
| lars512 wrote:
| I agree, it's quite in contrast to the attention paid in the
| writing itself.
| pilgrim0 wrote:
| 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?
| crispyambulance wrote:
| Yeah, it looks dreadful.
|
| We will get downvoted, of course, because omitting css is
| "cool" on HN.
| mgaunard wrote:
| Inclusive language is the last thing I need in my technical
| documents, thank you very much.
| xyzelement wrote:
| 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.
| ozim wrote:
| I have a slightly different observation.
|
| 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.
| xyzelement wrote:
| 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"
| rqtwteye wrote:
| 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.
| PartiallyTyped wrote:
| 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.
| kaycebasques wrote:
| > 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
___________________________________________________________________
(page generated 2023-10-28 23:00 UTC)