Multiple of my direct reports have identified technical writing and communication as an area they want to improve on. Besides coaching and gaining more experience, has anyone else found good resources/training/tools to improve technical writing?
I run a technical writing business and all of our writers are engineers, so helping engineers improve their writing is a large part of what I do.
Unfortunately, there's no silver bullet. Writing is like coding. You get better by doing it. There are no shortcuts. Write. A. Lot.
That said, as long as you are writing a lot (and many people will read the next part and try skipping the previous one), we do have some resources that help at [0].
We also ran a writing course a few times [1]. We have no immediate plans to run another cohort - in general we got very positive feedback but participants just weren't able to commit the time to practicing, and that is really the most important part. Happy to run it again, or a version of it, if you have a few people who would find it valuable and have time to commit. Details in profile.
This is basically what I did & do with my team. It requires you have someone who is already excellent at technical writing.
Document the principles of what makes good technical writing for your team.
Then you assign people on the team to document/write something, and have the person who is good at it edit their writing and discuss the changes in the framework of the principles you documented.
Lotta room for this to go wrong, maybe the person you thought was good at technical writing isn't that good, or can't communicate well. Maybe a lot of people on your team lack the language skills to do a good job. Maybe they don't understand things well enough themselves to communicate to others.
But in my case I was able to get 2 out of the 7 people who never really wrote to be good enough I'm proud to have them represent my team, which was a tremendous improvement.
>It requires you have someone who is already excellent at technical writing.
100%. You can probably help everyone on the team (to some degree) who is willing to do some work to improve. But you probably want one (or ideally two) people who can work with people and are the gate to actually publishing anything. They don't need to be a dedicated resource and don't even need to be "professional" editors. But they do need to be able to work with people and have strong writing (and copyedit) skills.
I would add that teams also need to commit to reading a lot, and to regularly editing what was previously written.
Writing in a culture where the written word doesn't have an impact, or where documents are skimmed once and go to die, is frustrating and will discourage people from trying.
I don't find writing to be difficult, but I do find getting started to be hard. My technical writing could be so much better if I had a template to choose from. The template would have all the headings and subheadings to get started.
Some examples of what I'm looking for might include:
* App/repo documentation for other developers to onboard (plus high level specs)
* Specific feature documentation and migration plan
* Technical post mortem documentation for a particular issue (focusing more on the technicals than a post mortem for management)
It sounds like you are running into the same problem that I did, which is that I wanted a structure to fill out with info. Don't do that. IMO, it's the hardest possible way to go about writing anything non-trivial.
Start writing in the middle of some random section in the middle of whatever you're trying to write. Jump around to different parts of the work if you get stuck. Edit it together at the end. You do not have to write from beginning to end in the same way that you don't sit down and write code from top to bottom.
If you really need a prompt, resist the urge to create a hierarchy of headers to just fill out. Writing is not just filling out a form. Try brainstorming a list of questions that your writing needs to answer. This has the added benefit of being able to divide up the work: you just give other people specific questions to answer. Let them organize the writing how it makes the most sense.
"Writing is like coding. You get better by doing it. There are no shortcuts. Write. A. Lot."
I disagree. You don't get better at something by just doing it a lot. You get better by doing something, evaluating how well you did (on a short feedback loop), then repeat a lot. Just doing and hoping that somehow you'll automatically evolve in the right direction won't get you anywhere. Coding implicitly has such a feedback loop. At the most basic level, your compiler will tell you about syntax. At a slightly higher level, you can see if your code does what you think it does. At a higher level still, in a matter of weeks or months you'll find out about your design decisions and architecture skills.
When writing, you don't get any such feedback. If you're very lucky and you write on quite straightforward topics like API docs, you can ask your readers 'did you get from this what you needed'. For anything more abstract, your readers most likely are not even qualified to assess how good your writing is. Overall, I strongly disagree with your notion that you should just start writing a lot and hoping for the best.
Well I didn't say "just write and hope for the best" and I agree with you to some extent, but most people will read books on writing, or follow frameworks, or watch videos, and not actually write.
Writing a lot and working with an editor and reading well-written works, and reading books on writing are all good for improving your writing. But if you have to pick one, pick writing. Most people pick all the others and skip the writing part.
Speaking as a sometime professional tech writer, your advice is good.
The best way I know to get rapidly better at technical writing is to write a lot with ongoing feedback from a capable professional editor. A good editor will teach you to catch and correct mistakes that you never knew were mistakes. Moreover, they'll teach you to understand why they're mistakes.
Unfortunately, the opportunity to write with the support of a capable technical editor is hard to come by. If you aren't working as a tech writer in a professional publications department somewhere, it might never happen.
Having to put your writing out there is creating the tension necessary to self-improve.
It also depends on what limitations you can see.
- Sometimes the problem is grammar and orthographic, in which case there's not much substitute to practice - pay attention to those ~~~ underlines in Word, write a lot and get corrected?
- Sometimes is with the flow of the document. It doesn't have the right level of details, it doesn't flow properly and is hard to follow. We have a couple training available for story-telling internally, they're not bad but they're internal. I've never really researched the topic deeply to be honest. From the feedback I receive, I'm blessed with decent writing skills - most of what I do is usually provide feedback on issues I can see: redundancy, improper level of detail, over-verbosity, lack of logic in the structure, putting the solution last, lack of an exec summary, lack of context, lack of diagrams, etc. Once again, practice ;
- Also setting the expectations (i.e. explaining why it's important, and stating that you expect them to proactively make an effort on that front). Sometimes when I see a repeating problem I make sure that they make a note of it ; it's crazy to me how sometimes people crave for feedback but don't write it down.
The fact that they identified that is 80% of the solution though, it is much harder to help someone who doesn't see that as a problem to begin with.
Yes it would have a different meaning. i meant to indicate that i want resources to help my team develop their writing skills as opposed to merely having the writing already existing be better
To me they mean two different things. "Upskill" tells me he wants the people on his team to develop better writing skills. "Improve" means he wants the writing to be better. A concrete example of the difference is that you can hire contractors to edit and publish the team's writing, which wouldn't necessarily make better writers of the members of his team, but it would improve the team's technical writing.
Off the top of my head, I don't know. I don't know what the character limit is for titles. That aside, one isn't clearer than the other -- at least not to me. And clarity is the most important part of technical writing to me. Sometimes jargon helps, sometimes it hurts, sometimes it is neutral.
I'm not a fan of those words either, but this is not helpful advice. Corporate argot, while it does signal a particular style, isn't inherently inferior at communication. A sentence will be just as clear, meaningful, and useful if the word "lessons" is substituted for "learnings". Focus on advice that will actually make a difference to the outcome, rather than unhelpfully signalling your disdain for corporatism.
Using jargon like "upskill" is indicative of the kind of thinking that leads to bad writing. It's a very easy to habit to fall into where you "write" by just sort of stitching together the nearest cliches, phrases, and jargon that come to mind. It's how we often talk and how we often write.
Unfortunately, writing like that is never good. By being a lazy pastiche of the familiar, it swaddles what you're actually trying to say in layers of non-information carrying fluff.
To improve your writing, you have to break that habit. You have to train yourself to introduce deliberate thought into the step between "vague idea in my head" and "linear sequence of words".
When you force yourself to cut out the jargon, that inconvient friction gives you a moment's pause to remind yourself to think about what you're trying to say.
Also, jargon usally has negative value. It says the same thing as simpler non-jargon words, but mixes some in-group signalling with it. In-group signalling can be a useful positive signal ("Trust me, I know what I'm talking about because you can see that I've absorbed the culture") but it can also be alienating for readers that don't feel like comfortable members of the tribe.
I try to use a little jargon here and there just to reassure people that I know the lingo and context of the local culture but otherwise I mostly focus on saying what I mean.
I agree with almost all of what you're saying, but I still stand by the point that _simply_ advising someone to "ban those words" is not helpful, especially when that guidance is delivered without the (correct and insightful!) description you gave of _why_ that jargon might be a "writing smell". A good writer can write meaningful, clear, useful communication which still uses buzzwords (they'd probably choose not to, but they _could_); a bad writer who is _only_ advised to avoid them will reproduce the same empty sentences with different words. Telling someone not to do something without telling them _why_ is the kind of thing you do to a child you're trying to keep safe, not something you do to an adult you're trying to train and...upskill ;)
More concisely - there is correlation, but not necessarily causation. Someone who uses these phrases will _probably_ also be someone who doesn't put much thought into their communication; but merely removing those phrases will not automatically, in-and-of-itself, cause them to become a better communicator.
I do think that even if they make no other changes, removing the jargon in favor of plain English will improve the quality of their writing. Maybe not as much as actually learning to reflect on what they're trying to say, but enough to be worth doing.
"Communication" starts with realizing that you have to meet people where they are, not expect them to adopt your style. You have to have some respect for them.
"Avoid unnecessary adverbs" would be another easy one ("unhelpfully signalling your disdain")
"unhelpfully" was deliberately chosen, to indicate that signalling disdain isn't helpful to the goal of teaching OP how to help their team. One could argue that it's redundant ("Focus on X, rather than Y" does imply that Y is unhelpful), but even so; reiteration for emphasis is a perfectly cromulent stylistic choice.
Surely if the OP is trying to help their team to communicate in a corporate environment, then teaching them the shibboleths like "upskill" will be helpful to (as you rightly suggest) meet the readers where they are? The team will be free to use them or not, as they choose. Whereas "banning" those words can only handicap their ability to corporate-cosplay, if that's something they want to do.
Regardless: I suggest you check the sibling thread (https://news.ycombinator.com/item?id=33805016), where we explore more relevant considerations - not just "what group are you masquerading as?", but also "does the use of this jargon result in fuzzy thinking or poor structure independent of the actual words used?" (/u/munificent suggests yes, I suggest that they're often correlated but there's not necessarily a causal link - cutting out those phrases will not _in itself_ result in better-considered, clearer, more-meaningful communication)
> "Communication" starts with realizing that you have to meet people where they are, not expect them to adopt your style. You have to have some respect for them.
Castigating people for word choices that you personally dislike while simultaneously advising them to "not expect them to adopt your style" is hilarious.
People give you a thing they want to improve on because they have to come up with something for reviews. Needing to improve on technical writing is innocuous, nobody really cares about it when making decisions about hiring or promotions or layoffs. You asked them 'what are your biggest weaknesses' and they said 'I care too much'.
This and https://diataxis.fr are about all the training you need. Beyond that you just need to organizationally commit to improving your docs. You yourself need to be the leader to keep reminding and explaining to stakeholders why it's important. Or else entropy will get you just like anything else in life.
A good concrete milestone is to create a spreadsheet of doc coverage. The rows are your key use cases and the columns are "tutorial", "guide", "explanation", "reference" (see Diataxis). Take a snapshot of your starting state. And then take a snapshot of your ending state (hopefully with more doc coverage for all your key use cases. It's a nice and clear story to tell to stakeholders. Explain the 4 Diataxis doc types to your stakeholders (basically just repeat the message on the Diataxis homepage). Most people intuitively get it and agree right away. And then you show them the before and after. "We started here and now our docs are much more comprehensive and here's a detailed breakdown to help convince."
I am a professional technical writer (edit: removed my current role because this is supposed to be my anon macro investing account... facepalm)
As a 20-year full-stack veteran (and once-upon-a-time English major), I second this. Even the best writers in literature had editors.
To gamify documentation and review, add a static analyzer that measures documentation coverage to CI. Not sure what your stack is, but for Ruby one I've had success with was Inch: https://github.com/rrrene/inch.
Once documentation is incorporated into the workflow with metrics, it can be addressed along with any other technical debt, enabling the team to improve their writing over time.
At my current company engineers aren't very good at technical writing, they were better at my previous org. I think one big difference was that we shared technical documentation much more widely before every initiative, engineers were effectively picking up good ideas and patterns from reading other engineers' docs. Over time the best habits were becoming documentation "standards" through copypasta natural selection.
Put the Bottom Line Up Front (contrary to most literary storytelling styles and to many logic structures) and Add Context to minimize context switching. The former is something people can often read and quickly internalize; the latter seems harder for people. "Hey, I'm looking at this Excel sheet; what do you think?" "Well, I think you're an idiot for not even telling me what spreadsheet you're looking at..."
I see plenty of advice on technical writing, which typically concentrates on how to structure things on a large scale, and how to make the words clear on a small scale.
But when (as very often happens) I'm reading documentation and I find it's less than satisfactory, the main problem is rarely the structure or the wording.
The main problem is nearly always that the information I need just isn't there.
So please, if you're training people to write, tell them to always keep these in mind as priorities: "Are the terms I used here defined elsewhere in the document, or else ones that I can assume all readers already know?", and "Have I actually said what this thing does?".
I don't know the answer but I'd expect the company needs to value it sufficiently to make it more valuable for them to spend the time doing proper technical writing than not. Usually this is not the case.
It's also an easy cop out to tell your manager when the discussion comes, "oh I want to improve my technical writing", "oh I want to improve my presentation skills". Ultimately, if the company is not encouraging that you're better off learning by yourself as an engineer.
I have a lot of non-native speakers on my team in which I am the lead. I write "skeletal" design docs for them after discussing what needs to be built, and have them finish the last mile. Over time, I reduce the amount of writing I do for them and expect them to be able to write on their own. Usually they get used to the process and recognize that they can copy paste a lot of the things they need to write from their previous docs.
Related tangent: get your team into the habit of writing things down more often. I split my time between VSCode and Obsidian, and capture devnotes as fodder for "real" documentation as a natural side effect of using a great tool for the job of thinking and designing and trying things and solving problems. Good devnotes are a superpower, and I'm convinced teams that realize this and adopt this approach will gain huge returns.
1. Have a coach or someone who is good at the skill help coach those who are not so great at it.
2. Have some way to capture data that allows you to know how well you're doing. Page views, engagement rates, happiness of content, etc.
The best approach is a combination of both. But the generic advice would be "write a lot and promote the ability to write a lot" and you'll figure out the deliberate practice side out later.
A deliberate practice environment has four elements:
1) Repeat exposure (aka volume of attempts)
2) Valid environment (a win is a win and a loss is a loss)
3) Timely feedback (you know immediately whether you won or lost)
4) Deliberate practice.
Deliberate practice without the other three is not complete.
Many technical people have an origin story that involves putting all their skill points into math & science, and sometimes they just need a little remedial English.
If you can learn to write well generally, you can apply that skill with technology as the subject matter.
Maybe the best advice from that book is to trim back word count. If you run a sentence thru your mind a coupla times you'll find a way to rephrase it that is more to the point and adds oomph. No waffling.
I’d recommend The first two sections of On Writing Well by William Zinsser - it’s short and following the guidelines will get you to clear understandable writing. If you forgot what is said, you can just read these short parts of the book again. The later sections can be referenced as needed.
Writing is hard. You need to edit again and again to get clarity. Programmers are used to this in code, but text is no different.
1. Have them pitch what they are working on multiple times to people that are not in their domain of expertise. We do poster sessions at our company, rapid 10 minute interactions hone the pitch.
2. Test having them use voice to text to write, some people’s internal voice is 100 times worse than when they speak out loud. (I wrote to 30% of my PhD thesis speaking.)
"Improve technical writing" is broad. First, I'd make sure everyone knows what kinds of docs it's possible to write. The Diátaxis Framework <https://diataxis.fr/> is good for that. Have a good discussion about what types of docs make sense for your environment -- who is the audience, what do they come with, what are they trying to do?
If they're curious about the skills of a technical writer, Google has some good courses. <https://developers.google.com/tech-writing> We have had some first time tech writers and they identified this as a useful resource.
Structure is an overlooked aspect of writing -- we're familiar with alphabetical lists of API function names but this is only useful for reference material. Much of writing consists of modelling the reader in your head and structuring your prose so that you don't confuse that reader by talking about things before they're defined. Readers are a lot like simple compilers in that respect -- if you want to talk about something before it's covered in detail, you have to declare it first. A lot of becoming a good writer is just internalizing the literary smells for "this will confuse".
Like everything they want to improve at, your engineers need to attempt writing and then receive feedback on it. When I give people feedback, it's not just a rewrite -- I talk them through my changes, from language choice to overall structure, and explain why I made the change and think the change is better than the original. And if they wrote something particularly well, then I check they understand why it works.
> if you want to talk about something before it's covered in detail, you have to declare it first.
For software, part of technical writing is providing the reader a conceptual model that they can work with in their mind.
But another part of technical writing is discovering that the user interface does not consistently use that conceptual model, or any other conceptual model, and so it inevitably brings in suggestions for improvements to UI/UX.
PS you asked for things like courses. I went looking when our first-time tech writer wanted to grow her skills. There are surprisingly few online options for anything beyond 101. If you do discover good 'uns, please share back. Thanks!
I think it depends on what kind of technical writing.
Are you interested in creating technical content for the outside world or content for internal consumption only. Do these individuals have strength in regular comms but trying to balance a technical voice - or more broadly need work in logic and rhetoric and writing in general?
Albeit a bit more specific than what you are asking, I attended a course from Chris Sanders on technical information security writing, and it was really good.
https://chrissanders.org/training/writing/
Enforce the Jeff Bezos AWS rules.
Hire people based on how well they can read code
Clear thinking, clear reading and clear writing are roughly the same thing / caused by same things eventually. You cannot have clear writing if you don't have clear thinking about the subject etc.
I think this is one that goes back to engagement experience. A lot of engineers have not read enough technical writing, and they've only read from their own bubble. As a start, have them go out and fully read technical writing from products they already use, and try to emulate that.
Don't use fake words like 'upskill' when you have perfectly good words like 'improve.' Get them copies of 'the little book' (Strunk and White) and the Economist Style Guide.
Also, pay attention to grammar, even in headlines: it will significantly improve your teams' output.
Beta test their output by giving it to first-time or newish users. Be willing to accept harsh criticism, because much technical writing is just really bad writing.
Minimize the length of sentences. Avoid repetition. Writers who are struggling often just rewrite the same information in slightly different ways, failing to explain their ideas clearly and wasting readers' time.
Humor and flair are good and help to make a good text memorable, but can also make a bad text annoying.
Pay attention to layout and pagination. Many technical documents are just read online by scrolling or consulted only occasionally, but for a large project some people are going to want hard copies, and they're the most likely to be your future power users.
Fonts, whitespace, heading weight etc. matter a lot. O'Reilly books owe part of their good reputation to their visual harmony. Packt also do good layouts.
By contrast, I'm reading a book from Apress at present and the body text/code fonts are too large. This makes it tiring to read: I am constantly flipping back and forth to refresh context because nothing fits on a single or double page. I've noticed the same complaint from buyers of other books by this publisher.
This also applies to things like tables of contents, which are one of the few things where repetition is appropriate. There's nothing more annoying when I'm trying to get familiar with some new library than scrolling through long texts of reference material in order to get an overview of what functions are available in each module.
Try to avoid the trap of a tutorial that stops shortly after 'hello world' followed by in-depth reference material, which often creates a yawning skill gap.
Between the two, there's room for discursive sections on why those functions exist - outlining some typical use cases, indicating which ones often pair with each other, and alluding to the outside knowledge that an intermediate-level coder or user might need to fully exploit the reference material.
This is a section where you can explain your design decisions and offer your readers a roadmap for deployment. Without this the reference material can resemble a list of tourist destinations in alphabetical order, with no clues about their geographic relationship.
Finally, writing is not a one-way process; you need to go through review and rewrite cycles. If you can't edit yourself it stands out on a first reading, even to people who can't articulate why. I delete 50% of everything I write and rework phrase/sentence/paragraph structure constantly. This comment went through 4 revisions and each paragraph was reworked 3 or 4 times while writing. Adding more words is the least interesting aspect of writing.
RedPen.cc, Vale.sh, TextLint, and LanguageTool are all invaluable NL linters. Low hanging fruit.
CodeSpell is a universal spell checker that understands most markup, as long as it's not some demonic XML/SGML specification from the Department of Defense.
If you really want to be a hardass, pre-commit hook based on a NL linter and a spellchecker.
OK, low hanging fruit. That's the first stop.
Second stop is to understand what needs to come out, and what needs to come in. This is going to depend on, well, what you're doing. Sketch something out with graphviz or plantuml to catch the flows. If you can, talk to the audience, and classify them if you can. In aerospace we have "maintenance levels" (lots of different acroterms for that) which delineate how well trained the audience needs to be to perform the task being considered. But anyway.
Third stop
How similar are the deliverables? Do you want to re-use any of the content? Or do you want to optimize on BDMs (Big Dumb Manuals) aka - maybe using a more scientific term here - unified manuals?
If you want to chunk the content up (using conditional content to filter out stuff), you have a few options, ranging from the XML world (DITA, DocBook, S1000D) to the world of lightweight markup (Asciidoc includes+conditional directives, MarkdownPP extension, RsT includes, etc). Broadly known as Component Content Systems. Don't get fast-talked; the vendors are insistent and they are all liars of one stripe or another. CCS isn't a cure-all, and XML isn't the "ultimate doc language". CCS isn't even an optimal fit for most purposes. But sometimes it is, and it can save you some time.
CCM/CCS is composed of the following:
*files* (DMs, topics, etc) that contain content,
*conditions* (applic, ditaval, etc) that customize content, and
*maps* (PMs, ditamaps, etc) that point to *files* to create a doc,
and a *product* that is being documented.
The relationship between the *product* and the *files+conditions+map(s)* is what's sometimes called document *architecture*.
*Architecture* can contain
1) the document "chunking" (how *files* are created/named) and
2) the *conditions* needed for a particular deliverable, and
3) how the *maps* that generate the deliverable tie the content deliverable to the *product*.
Currently, when people are just experimenting with the CCS concept, I advise them to try it out with Asciidoc, because you can do that right now, versus paying a hundred grand and waiting a few weeks for your DITA solution. Sure, some vendors are great, but a lot aren't, and they change around all the damn time. Particularly in the S1000D XML world.
I'm not sure I can agree hard enough with this sentence.
I always keep this sentence in my back locker too: "If your product isn't architected, don't try and architect your pubs"
The problem here is that everyone thinks their product is architected, because "architecture is good", and of course their product is Good.
There's a giant pile of false assertions here, but the worst is lack of self-knowledge. And if there is anything S1000D will punish harder than anything else - S1000D is nothing if not punishing - it is self-deception about what exactly a company is shipping to its hapless customers.
Unfortunately, there's no silver bullet. Writing is like coding. You get better by doing it. There are no shortcuts. Write. A. Lot.
That said, as long as you are writing a lot (and many people will read the next part and try skipping the previous one), we do have some resources that help at [0].
We also ran a writing course a few times [1]. We have no immediate plans to run another cohort - in general we got very positive feedback but participants just weren't able to commit the time to practicing, and that is really the most important part. Happy to run it again, or a version of it, if you have a few people who would find it valuable and have time to commit. Details in profile.
[0] https://ritza.co/handbook/improving-your-writing/how-do-I-be...
[1] https://styleguide.ritza.co/writing-course/