Summary of “Don’t twist the prose” by Larry Kunz

In this blog post, Larry talks about the importance of writing clear instructions. He talks about overthinking things usually makes for a more complex and difficult to understand scenario. As Larry mentioned, it is better to come back to something later with a fresh mind to effectively get your point across to the reader. Larry continues to back up his point by describing the importance of translation. He mentions how important it is for the person translating to have the background knowledge. He concludes the post by talking about the importance of verifying information before it actually gets released to the general public. He talks about the usability of the instructions and how nice it would have been had they verified their instructions with one English speaker.

Overall, I found this blog post really informative since it highlights the basic and most important concepts of technical communication/writing. It is important to keep in mind the target audience for technical communication, or for that matter, any piece of writing. I will continue to keep these things in mind as I improve my skills to become an effective communicator.

Smayan Daruka

Advertisements

Summary: “The Problem with FAQs in Documentation” by Tom Johnson

Frequently Asked Questions (FAQs) are not Frequently, nor Asked, nor Questions. According to Tom Johnson, FAQs are annoying and a bad idea.

FAQs start out as a collection of random thoughts someone on the team has about the software. These questions do not need to be about the use of the software, some may be better served in an “About Us” Section. Once testing starts, more input from actual users leads to more questions cluttering the FAQ. After launch is when companies should be making FAQs, but this time is when the team doubles the section. Where this leads is a monolith of “documentation” that is unmanageable and unhelpful.

Much of Johnson’s critique of this model in the first section is on the effort it requires. An important quote is “The team member…cranks out quick responses to these random questions with about the same effort as typing an email.” From the standpoint of a technical writer, this is not the correct way to write documentation. The proper way, in Johnson’s opinion, is to analyze the user’s goals and weave them into a story-like structure.

This is something that the FAQ format ignores, and is one of the main points in the second section. Proper documentation should start with a goal and provide a walk-through on achieving it. This would avoid Johnson’s second complaint, which is: As the list grows, it becomes less manageable and ruins the user experience. This is a direct consequence of throwing all questions together into one list, as he says, “…the trivial questions dilute focus from the more important questions.” Point four says that the questions are only miscellaneous questions, while point five points out how they are rarely from the actual users.

Combining all these points shows the following: the questions are not frequent, as they could have occurred once (or not at all); the product team could have imagined them, meaning they were not asked; and because the product team wrote them, they aren’t even questions.

The reason that product teams use FAQs instead of proper documentation is because they are easy to write. In this section, Johnson ties back to the point he made in the first – the effort required for FAQs is not enough for actual documentation. He also suggests a pattern to use instead of the Question and Answer pattern: Goal and steps required to accomplism it. This goal-driven narrative is required for proper documentation, but as Johnson states “…the difference is that the answer to these goal-oriented questions will entail a heck of a lot more information and detail than the random FAQ,” which is something that project teams may not want to invest.

Overall, Johnson believes that there should be a switch from FAQs as documentation to user stories in the form of goals and steps. FAQs can be added after the actual documentation, but if a question makes it to an FAQ, the actual documentation should change to account for it. FAQs should be reserved for 5-10 questions that are frequently asked by users – not places to put the story of your company.

~ Connor Shade

Wh*t Did You Say? Symbols for C*ss Words

Arlene Miller, blogger on bigwords101.com, discussed the history and current usage of how cuss words are altered in writing as well as on television and radio. Grawlix, which refers to strings of symbols that are often used in place of cuss words, date back to comic books from the 1880s. However, the term wasn’t coined until the 1960s. Sometimes this is referred to as profanitype, however that is just a slang term for grawlix.

In modern days, many different versions of grawlix are used. Oftentimes, a single asterisk is used to replace a central vowel in the cuss word. Common symbols that are used include &, #, %, !, @, and ?.

The Federal Communications Commission has restrictions on what can be said on television and radio. Broadcasters typically replace a cuss word with an audible beep which is now referred to as “bleeping” something out.

In the article, Arlene Miller mentions last how many authors, producers, and broadcasters will replace the swear with a more acceptable replacement term such as jerk, heck, or gosh, allowing them to get their point across in a more appropriate manner.

-Briana Goold

Is E-text better for studying?

People have a choice to decide whether they chose to read in print or electronically. Electronic texts are generally much cheaper than the actual hard copy. While college tuition is expensive to begin with, adding the cost of books only makes it worse. Therefore students will buy E-texts because of the lower cost. Students use E-textbooks for convenience, they don’t have to lug around textbooks rather just carry a tablet or laptop. But do people read as well on a screen than paper? According to an article from the NY Times, “Reading Literature on Screen: A Price for Convenience?” a study suggest that reading on a screen is less effective than reading on paper. Researchers study the differences between reading on a tablet and in print. The study took place in Norway, where 50 graduate students were asked to read the same short story by Elizabeth George, and were tested on it afterward.  The results clearly show that the students who read on paper did better than those who read off a screen. The students who read off the screen had a lower retention on the material than those who read from print. “They [students who used E-text] also performed almost twice as poorly when asked to arrange 14 plot points in the correct sequence.” The students who read off the E-text were unable to provide specific in-depth questions about plots. Students should consider which type of textbook best fits them, but remember that retaining specific information is much easier from print than E-text.

http://www.nytimes.com/2014/08/14/arts/reading-literature-on-screen-a-price-for-convenience.html?_r=1

-Mike Brown

Social Media and Sports

One of bloggers I chose to follow was Tristan Bishop, one of his recent blogs was “Winning the Social Media Superbowl”. In this blog Tristan uses images to connect the game of football to having a positive social media presence. He also compares social media marketing to running an offense and social customer service to coordinating a defense. In his blog he talks about “covering the whole field” and by that he went on to talk about sites and blogs, social channels and public conversations. Tristan also discussed that “offensively” you need to be able to promote and share your company’s products and ideas while “defensively” you need to be able to quickly respond to public customer challenges. And “recapping the season” is where you would asses where you are after a quarter, what did the company do well, where the company can improve and then set goals for the next “season”. This blog mad a lot of really strong connections between something I am familiar with, football, and not so familiar concepts such social marketing and social support. I thought this blog was really well composed and informational.

By Tallon Rood