
Ask HN: Short and Simple Technical Writing Standards - bloopernova
I&#x27;d like to impose a basic, simple set of writing standards for my geographically and culturally diverse team of operations folks.<p>I&#x27;m looking for a short list of Do&#x2F;Don&#x27;t items that people can refer to when writing documentation. Something that people with English as a (long used and familiar) second language can understand.<p>In a similar vein of thinking, I&#x27;ve run into multiple people in operations and development who feel like documentation is something someone else does. They don&#x27;t feel the need to write descriptive ticket comments. Nor do they want to learn about best practices and standards. I guess this feeds into the more general question of how do you push people to improve themselves?
======
zapperdapper
Useful starting point? [https://developer.nexmo.com/contribute/guides/writing-
style-...](https://developer.nexmo.com/contribute/guides/writing-style-guide)

------
afarrell
> how do you push people to improve themselves?

The first step is to write a clear explanation to sincerely answer why what
you're proposing is an improvement. How does the practice which you're
proposing fulfill a need?

------
manbearpiggy
This is something I have to think about too. Interested to know what kind of
tools you're using, as this may influence how you collaborate with these
teams.

------
DamonHD
On the last point, if you lead the team then you can point out that it is part
of their job, as executed professionally, to "write descriptive ticket
comments" and otherwise help themselves and colleagues get the job done. It's
not a matter of opinion or taste if you set the rules...

Remember that your being loved is less important than being effective.

Note, however, that reluctance may be embarrassment or lack of self confidence
in writing. I have worked with some remarkably good tech people who would do
anything to wriggle out of writing comments ... because they thought
themselves bad at it. Maybe point out perfection isn't the issue, capturing
the information that someone else can understand (grammar Nazis
notwithstanding) is...

~~~
bloopernova
That's a great point that I will definitely try to get across to everyone.

Getting just the relevant information is as simple as copying and pasting a
few urls and the contents of a terminal or two. It doesn't have to be perfect
prose or take hours to write!

