My Adventures in Troubleshooting (and the Importance of Good Technical Writing)
As a writing instructor, I often try to explain to my students that they have to be super clear about what they mean in their writing. Often, when we write something ourselves, we are making assumptions about what our audience will most likely know, but we’re often wrong. For example, if I’m writing a personal essay about my experience as a ballet dancer in my childhood, I might write about different positions like a la seconde or arabesque without ever explaining what the move means; I know very clearly what those moves are, so I might forget that my audience might not. Those kinds of assumptions have to be cleared up for a reader to completely understand the context a writer is discussing. Similarly, good technical writing needs to take into account that a complete novice with no knowledge of vocabulary terms or concepts needs to have literally everything explained to them in order to be able to utilize any forum or set of directions.
Spoiler alert: I had ZERO understanding of coding before I began this fellowship. It took me hours to set up my first GitHub repository because things like this are simply not intuitive me at all. So, when I started using Twine, I struggled immensely, especially because Twine has many multiple versions, and three different story formats within which to code. This means that the sidebar of the “Cookbook,” otherwise known as a how-to guide, looks like this:
I’m currently using Twine 2.0, which means the story format I began with was Harlowe. Thus, if I’m not on the Cookbook, but rather google something like “how to add google fonts to my passage in twine” I might get a bunch of unhelpful advice that only pertains to Version 1.4, when people were mostly using Sugarcube as the story format. Similarly, to use the Cookbook, a person has to have an intimate understanding of this update history to know how to navigate the guide in the first place. It’s been a frustrating ride, not without its ups and downs. In my next post, I’ll discuss a little further how I’ve navigated these guides to design my project.