Our great sponsors
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
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!
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.