How do you upskill your teams 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.

[0] https://ritza.co/handbook/improving-your-writing/how-do-I-be...

[1] https://styleguide.ritza.co/writing-course/

Tell them to start a blog.

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.

Here's one easy suggestion: stop using non-words like "upskill."

If you used "improve" how would that lose any meaning?

Start by banning words like "upskill" and "learnings"

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'.

Docs for Developers: An Engineer’s Field Guide to Technical Writing

https://link.springer.com/book/10.1007/978-1-4842-7217-6

How do you improve code quality at your company? Probably by code review.

The same works for technical writing. Have them review each other's documents. Not just for correctness, but for clarity and quality of writing.

(somewhat snarky) I would start by posing the question "How can I improve my team's writing". "Upskill" is more of a "downskill".

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.

I think spaced repetition with critical feedback is the best way to improve, but some frameworks can help.

This 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..."

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.

Deliberate practice.

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.

They could do worse than read The Elements of Style:

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.

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.

The same way you improve any skill:

Do it. A lot. With feedback; preferably quick feedback from people more skilled but any feedback is better than none.

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.)

Hi, former O'Reilly editor and current CTO here.

"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!

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.

I'm desperately interested in this as well. My direct reports have the same problem.

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.

Make them write, and find someone to be an editor.

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.