Thoughts on technical writing and accidentally gatekeeping communities

2020-07-23 00:00

The definition of “gatekeeping” I refer to in this post is Urban Dictionary’s “Gatekeeping”:

“When someone takes it upon themselves to decide who does or does not have access or rights to a community or identity.”

This post is a bit about thoughts and guilt that go through my head when writing for programmers or tech-oriented people. I enjoy programming for fun, both the learning process and the act of programming, but there has always been this guilt when I’m writing those README.mds for my programming projects.

I started learning to program three years ago, I’m on and off with programming books, websites on how to learn algorithms, cryptography challenges, or even just programming koans. I’m not a good programmer, but programming makes me really happy, and that happiness drives the creation of my programming projects, and my will to write good documentation, so someone can use my projects.

Regardless of how bad my programming is, I try to make my projects easy to use and easy to install for others. Even though I know most people won’t use them, having that feeling of sharing is priceless, and as I said, it drives me to keep creating and contributing to my non-existent community of users.

There is a problem though. I’m influenced by the many README.mds I’ve read, which also include the ones I have written, because I’m constantly going back to them and editing them, but I think that’s normal for most technical writers, or artists in general—nothing is ever perfect enough for you.

Having to go back and edit over and over again isn’t the problem, that’s art, the problem is this:

README.mds are written for technically-oriented people

You might say, “Yeah, but all you have to do is run sudo apt install racket, and then run raco exe file.rkt && chmod u+x file && ./file”

Okay, that’s great, but how is someone supposed to know what that even means if they have only been using Ubuntu for 3 days, and still doesn’t know why their audio isn’t working? How do they know that is something to run on the command line? Are they supposed to trust that running these commands are safe? Don’t hackers use Linux? What if I’m installing a key logger?

These are the people I want to appeal to when writing my README.mds, and so far, I feel like I’ve failed at that. If you haven’t been messing around with Ubuntu for more than two weeks, good luck on following the “simplest” README.md on X Git-hosting website.

Are we accidentally gatekeeping newcomers who are interested in the tech community because we assume so much when writing instructionals, just so developers have good documentation to reference? I’m not saying we should write for one or the other, but I am saying that it’s blocking new people, and being aware of this is important.

Imagine what kind of cool programs your painter friend Sherry could make with her artistic mind? I would love to see people from different fields getting into programming, but getting started is no easy task.

I’ve experienced developers, first hand, tell me “I don’t know why documentation has to be so long, like ‘just give me the command I need to run!’”, and hey, that’s true.

That can be annoying, but for people who are clueless about it, it’s helpful, and by not including that extra information that answers tech-writing questions such as:

We are accidentally gatekeeping new users from entering the tech community. Leaving out important information as to why the user is following this documentation in the first place, or what the difference between a “note” and a “tip” are little things that help welcome less tech-savvy people into tech communities.

If you look at tilde.town, it thrives with non-technical people because it curates itself towards non-technical people, and now it’s full of learners, and super cool community-oriented software, some even made by new comers to the technical community like me!

I guess this post is a big rant, but I just want to send a message to the tech community about the dangers of assumptions, how great it would be to have more people in the tech community, and that we should also thrive to include that “extra irrelevant information” that helps out less tech-savvy people.