News for hackers. Stuff that matters.
Re:Ask HN: How do you teach engineers to be better writers? by verdverm on Tuesday November 09, 2021 @05:52PM (#29168636)
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

There are no comments on this comment yet.