solstice
/
gopherhole


			
				
					
						
						
							
							<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>why is most documentation so bloated? - Archive - MayVaneDay Studios</title>
  </head>
  <body>
    <p align=center>
<b>MayVaneDay Studios (Gopher Edition)</b>
  </p>
  <p><b>why is most documentation so bloated?</b></p>
  <p><b>published: 12-6-2018</b></p>
  <p>&nbsp;</p>
<p>The past few weeks, I've been doing an awful lot of thinking about disability and accessibility. I used to be friends with a person (someone from the Lucine saga, although I won't say exactly who) who knew that he would eventually go blind and was already preparing for that. Throughout the past month in my Reproductive Tech class here at college, we've been talking about disabled people and the struggles they often face in society. And- of course- I'm autistic myself.</p>

<p>Accessibility is kind of a big deal. The vast majority of people who will read this probably have decent eyesight, and would have the hearing required to listen if I ever decided to branch out into videos or music instead of just plaintext. (There's a 99% chance that I won't, but that's a post for another day.) For blind people, we have image descriptions and screen readers. For deaf people, we have subtitles and transcripts and that annoying feature on smartphones where the flashlight flashes every time you get a notification and temporarily blinds everyone in the vicinity.</p>

<p>Accessibility is important for people with "invisible" disabilities, as well. Anxious users trying to fill out web forms might benefit from simple structuring in pages and frequent reassuring that they are, in fact, going to the right place for whatever they need help with. Users with depression or executive dysfunction would benefit greatly from especially stable software that only crashes rarely, if at all, because if they pour a significant amount of time into a task and then that task crashes and takes all their work to the gutter with it, they might not have the mental energy to return to whatever task they were trying to do. And that would help users with attention disorders- gods know it's taking them a great amount of willpower to focus on something; if they get interrupted with a crash and have to do it all over again, they might not have the energy to refocus and redo their work.</p>

<p>Which brings me to the titular question: <b>why is most documentation so bloated?</b></p>

<p>I'm currently taking a class called Computer Science I. The required textbook is a <del>thicc</del> thick slab of 1% actual examples of what they're trying to illustrate and 99% wordy explanations as to how one would arrive at the example. Which blows, because I don't learn by sitting through boring lectures- I take an example and reverse-engineer it to figure out how it runs on its own. Sit me down in front of a computer with Unity and a manual and I couldn't make a video game in a thousand years, but sit me in front of my favorite video game and I'll start infodumping about all the little quirks I've noticed in the software and how the game mechanics work and even a rough imagining of the data types and if/whens and while loops contained within. A rudimentary understanding of the code within, even if it's proprietary and the source will never see the light of day.</p>

<p>When I'm having a mental breakdown and rushing to get a coding project done, I don't want to have to wade through all the explanations of how the code works. I want a known-good working example I can tweak to my own workings, and I want it up front. If I ever feel like reading the wordy documentations, I should be able to scroll down a bit and get to all of them, but only when I have the time to.</p>

<p>For example: I was working earier today on <a href="https://validator.w3.org/nu/?doc=https%3A%2F%2Fmayvaneday.keybase.pub%2F">getting my website to validate</a>. It yelled at me for forgetting to set the document language and pointed me to a documentation page. But <a href="https://www.w3.org/International/techniques/authoring-html#textprocessing">that page</a> was full of links, which broke without Javascript, and those links were <i>actually</i> pop-down menus holding more links, and <a href="https://www.w3.org/International/questions/qa-html-language-declarations">two pages later</a>, I finally found the relevant tag- hidden under a bunch of explanatory text.</p>

<p>I'd love to write a replacement for that brick of a textbook, one more suited for attention-deficit people, one with the scales tipped (pun intended ;) ) in favor of examples instead of extraneous explanations. Wouldn't that be a nice manual to read? Would certainly have saved me a lot of time.</p>
  </body>
  </html>