12 ms·
Writing for Professional and Technical Audiences
- Daub 3y agoSolid 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 3y agoAnd their ability to not just zero in on gaps but creatively twist things to their favor.
- cyrnel 3y agoGood advice! I recommend this book, especially chapters 1 and 9: https://archive.org/details/technicalcommuni0000ande_y9j8/page/n5/mode/2up https://archive.org/details/technicalcommuni0000ande_y9j8/pa...
- GinsengJar 3y agoGreat 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 3y agoI 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 3y agoHere'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 3y agoOne 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 3y agoAll 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 3y agoJust make sure you explain every technical term or acronym before you use it.
- growingkittens 3y agoDepending 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 3y agoIt'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.
- euroderf 3y agoThis 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.
- SoftTalker 3y ago> 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 3y agoIf clarity is the problem then one should use an actual name instead of a pronoun anyway.
- bazoom42 3y agoCan 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 3y agoIt 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 3y agoAs 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 3y agoA 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.
- adhesive_wombat 3y agoAll 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 3y ago> 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 3y agoMy 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?
- jillesvangurp 3y agoThe 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 3y agoI agree, it’s quite in contrast to the attention paid in the writing itself.
- pilgrim0 3y agoYes. 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?
- uaas 3y agoYou literally mean that you exclusively read on mobile?
- crispyambulance 3y agoYeah, it looks dreadful. We will get downvoted, of course, because omitting css is "cool" on HN.
- mgaunard 3y agoInclusive language is the last thing I need in my technical documents, thank you very much.
- xyzelement 3y agoIt’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 3y agoI 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 3y agoThat’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 3y agoI 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.
- kaycebasques 3y ago> 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-into-2022-state-of-devops-report-on-documentation 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
- deleted 3y ago[deleted]