A major part of my job at large technology companies has been reading, writing, and editing documents explaining various issues and what can be done to address them. I think it’s a more important skill than people generally realize, as it may be the one way to reach someone in a different time zone, or who couldn’t make a meeting, or who you will never speak with in person. Effectively written documents also have a way of hanging around, so investing in them can pay back over the long term.
I’ve also learned through experience that there is value in good writing in ways that aren’t always obvious. A well-articulated error message in a log file or api response can save an engineer significant time, for example.
Over the years I’ve gathered a set of guidelines that have worked for me. I’ve made it a habit of sharing this type of stuff internally at the companies I work at, but none of this is specific to any company, so I’d like to share publicly this time.
This list benefited from feedback and revisions provided by professional colleagues of mine. I won’t name them here, but thank you to those of you who read drafts of this and offered feedback.