Image Image Image Image Image Image Image Image Image


April 13, 2018

My Adventures in Troubleshooting (and the Importance of Good Technical Writing)

April 13, 2018 | By | No Comments

Perhaps the most important thing I’ve learned during this CHI project is how necessary various forums on HTML and CSS are to a person’s progress on a project. Over the last few weeks, I’ve had to rely entirely on the Twine Cookbook and googling random questions online to try to understand what I need to change. Programs like Code Academy  are useful is developing a basic understanding of how to understand and use html, css, and javascript. But, in the end I’ve spent way more time perusing the cookbook and reading forums online for specific solutions for the problems I’m having. For this reason, I’ve also learned the importance of good technical writing. Which, PS, turns out a lot programmers aren’t the greatest at that.

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.

Submit a Comment