Good & Bad Instructions

In this post I will analyze two examples of instructions found online, one that represents a good set of instructions, and one that is not so good.

The good set of instructions is titled “How to Make a Kindle Paperwhite Protective Book Case” and can be found here: http://snapguide.com/guides/make-a-kindle-paperwhite-protective-book-case. As the title suggests, the instructions walk you through how to create a case for an Amazon Kindle Paperwhite out of a book. These instructions are good for the following reasons.
– The final product is clearly identified both at the beginning of the instructions and at the end.
– All of the necessary materials and tools are identified in a picture in the very first slide of the instructions. They are also clearly enumerated in the “Supplies” tab.
– There is no indication of how long it will take, but by simply reading through the instructions quickly you can determine that it will not be a very short process – the longest step by far will be gluing all the pages together.
– This is very obviously going to be a solo job.
– The steps are in a logical sequence – it progresses from collecting the materials, to cutting out the pages, then to gluing.
– The steps are clear and concise; there are only 8 slides, and each one states clearly what you should be doing.
– There are no safety warnings, but perhaps there should be, especially regarding the “sharp razor knife.”
– There are no age requirements, but again perhaps there should be because of the knife.
– There are sufficient visual aids included with each step

The bad set of instructions is titled “how to take screen shots” and can be found here: http://www.instructables.com/id/how-to-take-screen-shots. Using the same categories as above, let’s determine why these instructions are so awful.
– The final product is visible but not clearly identified; the first step shows a screenshot, but nothing identifies it as what you are trying to create.
– The materials listed are not necessary for taking screenshots.
– No tools are listed.
– There is no indication of how long it will take, but reading through the instructions makes it clear that it will not take long.
– This is clearly a solo activity
– The steps are in a logical sequence, but there are additional steps included that are completely unnecessary (notably: copying the image into MS Paint, and uploading it to the Internet)
– The steps are not clear at all. The writer of the instructions assumes that everyone will be using a computer that has a “prt sc sys rq” button on it. Many computers do not have this button, or have different text on it. Also, he highlights the “fn” button because apparently it needs to be pressed on his laptop, but that is definitely not the case for all computers. The steps are also ineffective because of the vast amount of misspellings and grammar mistakes (e.g. “ya i know never head of it but it is their!”)
– There are no safety warnings, but none are necessary
– There are no age requirements, but none are necessary
– There are visual aids, but they are not applicable to all computers (as stated above), so they are not useful.

Advertisements

Interview with Cameron Buescher of Pariveda Solutions

On 2/5/13, I conducted an interview via email with Cameron Buescher, a software engineering consultant at Pariveda Solutions on the topic of writing in the field of software engineering. Below is a transcript of the interview:

1. How much writing would you say that you do on a daily basis?

On a daily basis I write a lot of emails. That may seem mundane, but writing good ones has been one of the most useful things I’ve learned since being here. Every few weeks I’ll also do some technical documentation work.

2. What types of writing do you do for internal use? External?

Internal: I’m working on a self-evaluation right now, although I don’t know a particular stereotype that falls under.
External: Technical documentation–text, diagrams, and graphics.
Both: Email.

3. What is the process for editing/proofreading documents you produce?
Email: I proofread for several things:
– structure: did I state the most important things first, followed by supporting material in descending order of importance?
– purpose: was I clear about why I’m sending it; is it an FYI or a TODO for the recipient?
– context: did I provide enough for them to understand what I’m talking about, and did I make any assumptions about what they know?
Technical stuff: usually there is review and proofreading by peers and managers in addition to my normal mental checks.
In general:
– I try to test my writing on how it sounds out loud. If it sounds bad out loud I reword.
– I generally consider the most concise way the best, and try to cut out anything that’s irrelevant and/or “fluffy”.

4. Would you say that the majority of your writing is collaborative or individual? What kinds are collaborative, and what kinds are individual?
Some of both, although the significant pieces are almost always collaborative.

The last two questions refer to the following 6 genres of writing, as defined in Philip Rubens’ “Science and Technical Writing”:
– Marketing – provides summary and overview information aimed at persuading the audience to initiate an action (posters, online/print ads, social media, etc.)
– Conceptual – provides background and theoretical information to explain central ideas (textbooks, trade journals, etc.)
– Procedural – helps the user accomplish an immediate task, imparting short-term knowledge (cookbooks, assembly instructions, etc.)
– Tutorial – teaches a skill, imparting long-term knowledge necessary to accomplish important tasks
– Job aid – provides quick-reference information for essential tasks
– Referential – provides encyclopedic, in-depth information about a product or service

5. Which of these genres (top 3) do documents (informal or formal) that you write at work fall into? Can you describe some examples of documents you’ve written in each of the top three?
– Job aid and Referential: technical documentation for projects. These docs can cover things ranging in detail from high-level architecture to implementation-level details. These can really fall in nearly every category above, although they lean towards these categories in general. Unfortunately I don’t know of one I can send you… sorry.
– Procedural: emails. (Boring, sorry). I attached one which I recently sent asking about Dallas networking groups.

6. Which of these genres (top 3) do you most commonly read at work? Can you describe some examples of documents you’ve read in each of the top three?
– Referential: lots of technical documentation (MSDN, jQuery, [insert any framework/technology documentation]). One piece related to Windows Azure: http://msdn.microsoft.com/en-us/library/windowsazure/dd894031.aspx.
– Job aid: quick fixes to problems via internet search (Stackoverflow for something I hit today: http://stackoverflow.com/questions/2239143/automapper-how-to-map-to-constructor-parameters-instead-of-property-setters )
– Conceptual: some tech, some business. Examples include http://www.codeproject.com/Articles/133738/Quick-Ways-to-Boost-Performance-and-Scalability-of and http://www.premiumbeat.com/blog/lessons-in-creativity-from-pixar/

Responding to a critique of The Return of the King

A critic on “Christian Science Monitor” reviewed the final installment of Peter Jackson’s “The Lord of the Rings” trilogy, “The Return of the King”, as a 50 out of 100 on metacritic.com. The critic made three major claims. First, he claimed that Jackson’s transition of Tolkien’s story into “cinematic terms” was “uninspired”. Second, he claimed that the movie was too long and was unable to keep the excitement that he acknowledged in a few scenes consistent throughout the movie. Third, he claimed that, save for Ian McKellan and Andy Serkis, the acting was “dull”.

His score was by far the lowest on metacritic (the average score is 94), so clearly there must have been something astray in his analysis. The three points can be individually countered.

First, the film was clearly up to cinematic standards. The film won 11 Oscars, which are generally accepted as the most well-respected award in American Film. If the movie was “uninspired”, it could not have accomplished this.

Second, the movie was not too long. An enormous amount of people were willing to sit through the whole 3+ hours, and most were satisfied by it (as evidenced by the high score on metacritic).

As for the critic’s third point, many organizations that give awards for movies disagree with this, giving awards such as “Oustanding Performance by a Cast in a Motion Picture” (Screen Actor’s Guild) and “Best Supporting Actor” (Seattle Film Critics – for Sean Astin).

The three points can be countered, so it stands the reason that this critic’s review was “uninspired”, rather than the movie itself.

My Favorite Movie

My favorite movie is probably the Lord of the Rings trilogy from Peter Jackson, though it is not without competition. These movies were my first introduction to the incredible world created by Tolkien, and inspired me to later read the trilogy of novels that the movies were based on.

There are several things I like about the movies. One is that the story is not what it seems to be at face value. Watching the movie for the first time, one would think that the primary story is about destroying an evil ring. However, when investigated further, one finds that it is really much more about the journey than the end result. Once one comes to this realization, it answers the oft-asked question: Why didn’t the eagles, who helped out at the beginning and saved them at the end, not just fly the ring to Mordor and drop it in Mt. Doom? The answer is simple: that would miss the point. The real story is the bond of friendship that grows between Frodo and Sam, the reinstating of the proper king of Gondor, and the tragedy of Smeagol.

Another, more “surface-level”, aspect of the movies that I enjoyed was the reserved nature of the CGI used. The movies were made in the early 2000s, so the capability of computer graphics was far more limited than it is today. Jackson realized this, and unlike many movies of the time, was not overly flashy with the computer generated imagery. Because of this, these movies are still watchable and believable a decade later.

A third aspect of the movies that I like is the excellent performances by many of the actors, especially Elijah Wood and Ian McKellen. They played their parts convincingly, and were true to the characters they represented from the novels.

I highly recommend these movies to anyone who has not seen them (and who has about 10 hours to spare).