Ask HN: How do you upskill your teams technical writing?
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?
75 comments
[ 3.1 ms ] story [ 67.8 ms ] threadThis article resonates strongly with me: https://www.animalz.co/blog/bottom-line-up-front/ on its two main points:
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..."
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.
https://link.springer.com/book/10.1007/978-1-4842-7217-6
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)
Part of that is about giving people time to write.
I have seen multiple times that companies want technical documents...as well as a full weeks coding
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/
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.
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.
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.
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.
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.
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.
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)
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.
"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")
Castigating people for word choices that you personally dislike while simultaneously advising them to "not expect them to adopt your style" is hilarious.
Corporate is widely and justifiably condemned. It's not just a personal thing. Even on this thread.
Calling it "hilarious" was definitely the work of a flamer though.
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.
If you have respect for your readers, then you use language they can relate to.
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)
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.
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.
If you used "improve" how would that lose any meaning?
There's two main ways to do that.
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.
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 need help at the micro level of putting words together well, check out Lynn Dupre's "Bugs in Writing: A Guide to Debugging Your Prose" <https://www.amazon.com/BUGS-Writing-Revised-Guide-Debugging/...>.
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.
Good luck!
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.
https://gutenberg.org/ebooks/37134
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.
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?".
The same works for technical writing. Have them review each other's documents. Not just for correctness, but for clarity and quality of writing.
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.
Do it. A lot. With feedback; preferably quick feedback from people more skilled but any feedback is better than none.