clone url: git://git.m455.casa/m455.casa
html/archive/2020/thoughts-on-technical-writing-and-accidentally-gatekeeping-communities.html
| 1 | <!DOCTYPE html> |
| 2 | <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> |
| 3 | <head> |
| 4 | <meta charset="utf-8" /> |
| 5 | <meta name="generator" content="pandoc" /> |
| 6 | <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> |
| 7 | <title>Thoughts on technical writing and accidentally gatekeeping communities</title> |
| 8 | <style> |
| 9 | code{white-space: pre-wrap;} |
| 10 | span.smallcaps{font-variant: small-caps;} |
| 11 | span.underline{text-decoration: underline;} |
| 12 | div.column{display: inline-block; vertical-align: top; width: 50%;} |
| 13 | div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} |
| 14 | ul.task-list{list-style: none;} |
| 15 | </style> |
| 16 | <style> |
| 17 | body { |
| 18 | line-height: 1.5; |
| 19 | font-family: sans-serif; |
| 20 | font-size: 18px; |
| 21 | margin: 20px auto; |
| 22 | max-width: 630px; |
| 23 | } |
| 24 | |
| 25 | a { |
| 26 | color: blue; |
| 27 | } |
| 28 | |
| 29 | code, pre { |
| 30 | background-color: #fddee3; |
| 31 | font-size: 14px; |
| 32 | } |
| 33 | |
| 34 | pre { |
| 35 | padding: 25px 25px; |
| 36 | overflow: auto; |
| 37 | } |
| 38 | |
| 39 | pre code { |
| 40 | white-space: pre; |
| 41 | } |
| 42 | |
| 43 | img { |
| 44 | max-width: 100%; |
| 45 | } |
| 46 | |
| 47 | table { |
| 48 | border-collapse: collapse; |
| 49 | } |
| 50 | |
| 51 | table caption { |
| 52 | font-weight: bold; |
| 53 | margin: 10px 0px; |
| 54 | text-align: left; |
| 55 | } |
| 56 | |
| 57 | th, td { |
| 58 | border: 1px solid #000; |
| 59 | padding: 4px; |
| 60 | } |
| 61 | |
| 62 | blockquote { |
| 63 | border-left: 3px solid #000; |
| 64 | padding-left: 10px; |
| 65 | } |
| 66 | |
| 67 | .border { |
| 68 | border: 1px solid #000; |
| 69 | margin: 25px 0px; |
| 70 | padding: 5px 25px; |
| 71 | } |
| 72 | |
| 73 | @media only screen and (max-width: 700px) { |
| 74 | body { |
| 75 | margin: 10px; |
| 76 | } |
| 77 | } |
| 78 | |
| 79 | @media (prefers-color-scheme: dark) { |
| 80 | body { |
| 81 | background-color: #111; |
| 82 | color: #eee; |
| 83 | } |
| 84 | a { |
| 85 | color: #009fff; |
| 86 | } |
| 87 | code, pre { |
| 88 | background-color: #111; |
| 89 | color: #fd6363; |
| 90 | } |
| 91 | pre { |
| 92 | padding: 15px 25px; |
| 93 | } |
| 94 | blockquote { |
| 95 | border-left: 3px solid #666; |
| 96 | } |
| 97 | .border, th, td { |
| 98 | border: 1px solid #666; |
| 99 | } |
| 100 | } |
| 101 | </style> |
| 102 | </head> |
| 103 | <body> |
| 104 | <main> |
| 105 | <h2 id="thoughts-on-technical-writing-and-accidentally-gatekeeping-communities">Thoughts on technical writing and accidentally gatekeeping communities</h2> |
| 106 | <p>2020-07-23 00:00</p> |
| 107 | <p>The definition of “gatekeeping” I refer to in this post is <a href="https://www.urbandictionary.com/define.php?term=Gatekeeping">Urban Dictionary’s “Gatekeeping”</a>:</p> |
| 108 | <blockquote> |
| 109 | <p>“When someone takes it upon themselves to decide who does or does not have access or rights to a community or identity.”</p> |
| 110 | </blockquote> |
| 111 | <p>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 <code>README.md</code>s for my programming projects.</p> |
| 112 | <p>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.</p> |
| 113 | <p>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.</p> |
| 114 | <p>There is a problem though. I’m influenced by the many <code>README.md</code>s 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.</p> |
| 115 | <p>Having to go back and edit over and over again isn’t the problem, that’s art, the problem is this:</p> |
| 116 | <p><strong><code>README.md</code>s are written for technically-oriented people</strong></p> |
| 117 | <p>You might say, “Yeah, but all you have to do is run <code>sudo apt install racket</code>, and then run <code>raco exe file.rkt && chmod u+x file && ./file</code>”</p> |
| 118 | <p>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?</p> |
| 119 | <p>These are the people I want to appeal to when writing my <code>README.md</code>s, 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” <code>README.md</code> on X Git-hosting website.</p> |
| 120 | <p>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.</p> |
| 121 | <p>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.</p> |
| 122 | <p>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.</p> |
| 123 | <p>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:</p> |
| 124 | <ul> |
| 125 | <li>“how does this benefit the user?”</li> |
| 126 | <li>“what significance does this have to the user?”</li> |
| 127 | <li>“does the user know what will happen after running this?”</li> |
| 128 | <li>and many more</li> |
| 129 | </ul> |
| 130 | <p>We are accidentally gatekeeping new users from entering the tech community. Leaving out important information as to <strong>why</strong> 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.</p> |
| 131 | <p>If you look at <a href="https://tilde.town">tilde.town</a>, 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!</p> |
| 132 | <p>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.</p> |
| 133 | </main> |
| 134 | </body> |
| 135 | </html> |