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)
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.
This is how I feel about it too
Depends on who is the reader.
My team members (Many people are involved in discussion): Let's us do this.
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.
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.
Yes! This! Thank you 🙏
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!
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.
I just describe myself doing it as I suffer from crippling narcissism.
Somehow I'm reminded of this:
😂😂😂
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.