DEV Community

Cover image for How do you refer to the reader?
Scott Spence
Scott Spence

Posted on

How do you refer to the reader?

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.

Top comments (14)

iam_timsmith profile image
Tim Smith

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.

spences10 profile image
Scott Spence

This is how I feel about it too

hpj1992 profile image
Harshit • Edited

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

goyo profile image
Grzegorz Ziemonski

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

hpj1992 profile image

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.

itsasine profile image
ItsASine (Kayla)

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.

spences10 profile image
Scott Spence

Yes! This! Thank you 🙏

bitdweller profile image
Pedro Pimenta

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.

rsdesoto profile image

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!

lysofdev profile image
Esteban Hernández

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

kayis profile image
K (he/him) • Edited

Somehow I'm reminded of this:

One would not be considered shitted

spences10 profile image
Scott Spence


itr13 profile image
Mikael Klages

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 (...)"

qm3ster profile image
Mihail Malo

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.