re: How do you refer to the reader? VIEW POST


Depends on the audience and the topic.

If I'm writing an environment set up guide, I'm telling you what to do to your computer to set up your environment. Like, you're going to have to own this, so yes, I have authority on how to do it and if you don't follow this exactly, shit will likely break and you can't work.

If I'm writing a release guide or something about how to use a technology, we're deploying this to production this way or we're learning how to do the thing. We're both on the same level but I happen to know something you don't.

If I'm writing something more public facing, I'm casual and friendly, but I do still need to enforce my authority on the subject, so it's still more now you do this and that.

At work, most tend to be ultra formal and don't refer to a reader at all. Do x, insert y into slot z. I'm the odd one for being conversational like I'm talking to actual people who need to know how to do a thing. "Do x, it'll probably throw some warnings but it's okay to ignore those. Insert y forcefully into slot z; it'll feel like you're going to break it." Rawr, saying what it'll feel like isn't technical documentation. I don't care; I needed to know that when I did this the first time so I'm saving future people that panic.

code of conduct - report abuse