How do you teach engineers to be better writers?

Question

We recently put in place more a formal requirement around technical specifications in my company, which has revealed a wide range of writing skills on the team. (Unsurprisingly, the engineers who were already writing extensive specs before the requirement was put in place are generally effective writers. Those who weren't doing so are less so.)Some of the engineers are really quite poor writers. Their specs have shoddy punctuation, spelling, and grammar, but even worse are usually poorly organized, difficult to understand, and incomplete.We are an all-remote company, so written communication is especially important. I am thinking we need to considerably elevate the importance of writing samples during the hiring process, but for engineers who are already working for us (and who in general are positive contributors), what can we do to improve their writing skills?My experience is that writing is one of those things that some people have a knack for and others don't (kind of like coding), so I would love to hear from people who made the transition from bad to competent writing. We're not looking for Shakespeare. Just clear, grammatical, organized prose.

verdverm · Accepted Answer

Have guidelines like complete sentences, proper grammar. Create templates for different purposes.
Given them many examples of good writing, both internal and external.
Let and make them iterate, don't accept until it is acceptable.
Use slack to mention them when what they wrote was helpful. Generally give praise and positive feedback.
Make the documents collaborative, living. Provide clear changes desired. File bugs for incomplete or incorrect docs. Generally make docs an acceptance criteria where appropriate.
I'm building a list of resources here: https://verdverm.com/resources/dev-docs/
(I have a few more to add, will try to get to that later tonight)
Documentation is cultural, it takes time to change this. It will improve with time and effort

_448 · Answer

* For internal consumption, the code should be THE doc.
* For external consumption, the comment of the public interface should be THE doc. Lot of programming languages have tools to write and convert comments to docs.
Writing is improved by reading other's work. Ask these engineers to read fictional and non-fictional books(novels, autobiographies, biographies etc), ask them to read anything written by other engineers excellent at writing: Paul Graham, Linus Torvalds etc. Paul Graham has several articles on writing. Also, both Paul and Linus have mentioned that they re-review their writing before posting. Also ask them to watch good online debates. This all helps in putting ideas to words. Most of the time engineers know what they want to say, but they don't know how to say it.

elenaturner · Answer

Get them use Grammarly. 80% of the issues you mentioned will be fixed, and rest 20% will be either not a big deal or getting their writeup reviewed by an editor will greatly help them overcome the deficiencies shortly.

bradwood · Answer

You need to be asking yourself why you need so much documentation. Engineers writing docs is a bad use of time. Find a way to make the engineering obviate the need for docs is probably better.Otherwise, maybe hire some technical writers