Ask HN: Short and Simple Technical Writing Standards | Hacker News Reader

Ask HN: Short and Simple Technical Writing Standards

11 pointsbloopernova5 comments

I'd like to impose a basic, simple set of writing standards for my geographically and culturally diverse team of operations folks.

I'm looking for a short list of Do/Don'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.

In a similar vein of thinking, I've run into multiple people in operations and development who feel like documentation is something someone else does. They don'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?

View on HN

Useful starting point? https://developer.nexmo.com/contribute/guides/writing-style-...

> 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?

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.

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

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!

Reply on news.ycombinator.com