How do you refer to the reader?

twitter logo github logo ・1 min read

Photo by Toa Heftiba on Unsplash

Had this thought, I have always written anything I learn as a, "hey let's do this together" sort of post.

If you write a guide do you do it the same way or as a direct got to a, do b sort of thing?

I have been going through a lot of the DigitialOcean documentation which is beautufully written and now I'n not sure I'm going about writing guides the right way.

twitter logo DISCUSS (14)
markdown guide
 

I was always told that people don’t like being told what to do and using I/you language sounds divisive like I’m up here and you’re down there. I usually try to stick to β€œwe” because it’s inclusive and feels more like guidance than a list of instructions if that makes sense.

 
 

Depends on who is the reader.

My team members (Many people are involved in discussion): Let's us do this.

  • But many time, intention without plan is useless. So make sure to say "We will have to do this by THIS_DATE. Here is the ticket/task for the same."

Mentee/Junior/Colleague (Only 2 people are involved): Can you please do this to our database/service?

General reader: Do this to your database so that you can achieve this...

 

What's the difference between a "team member" and a "Junior/Colleague"?

 

Thanks. I corrected.

I meant team members. When I am addressing in front of all the team members.

Mentee/Junior/Colleague: Whenever only 2 people are involved. I make sure any of us takes the ownership of the work.

 

For "general public" guides I prefer you because it makes me feel empowered, like I'm learning and accomplishing something on my own. Whereas using we makes me feel more like an helpless child that needs to be guided in every step.

But in the end it doesn't matter, if the guide is useful we'll like it and you'll always have opposite tastes like Tim Smith's and mine.

 

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.

 
 

Generally speaking, for internal planning purposes, I prefer "we" (i.e., "what do we need to do today?") since we're a team and working together. Even when reviewing each person's individual tasks, I prefer saying, "Jane will take databases" or similar vs. "Jane, you take databases".

For communicating with users, as either someone looking up instructions or someone writing instructions -- I realize this is kind of a weird stance, but I strongly prefer polite instructions because otherwise it feels rather presumptive to talk like we're friends and colleagues!

 

I just describe myself doing it as I suffer from crippling narcissism.

 
 

Sometimes I, sometimes you, a few times one, but most of the time I remove the doer completely, and just say "It's possible to (...)" or "One way is to (...)"

 

It does x to the database, or else it gets the hose again.
Even I have standards, I would never claim joint ownership of the database of the reader following along.

Classic DEV Post from Jan 18

Getting Started with Test Driven Development

An introduction to test driven development.

Scott Spence profile image
Dev since 2007, now learning modern web development techniques.

The All-Time Best

Browse Top Articles