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

Summary: What Technical Writing Trends Will We See in 2018?

In one of his most recent posts, Tom Johnson recaps the technical writing trends of 2017 before predicting what 2018 would bring to the world of technical communication. He begins by mentioning that his most popular blog post in 2017 was on the topic of trends which, according to Johnson, “suggests tech writers are interested in keeping up with what they perceive as a constantly changing landscape for their jobs.” This seems to be true for professionals in most fields. Specialists never want to appear behind their peers or to seem as though they are not up to date with the current practices or technologies in their profession. A few technical communication trends Johnson mentioned were chatbots and voice interactions, podcasts, and docs – as – code tooling. These and a few other themes emerged in the technical communication world this past year and stood out to Johnson.

As he continues, Tom Johnson predicts what will become popular in 2018. He anticipates “tech writers will play more cross-functional, interdisciplinary roles in order to establish value as generalists,” meaning technical writers will likely write fewer technical documents but become more involved in the “editing, publishing, and curating” phases of document development. Johnson believes “hyperspecialization” will be the main reason for this change. As it becomes more common for “professionals [to] study one specific field, going in depth in a particular detail in the field,” technical writers are finding it difficult to come up with content for documents simply because the required information is so detailed. For this reason, Johnson predicts technical writers will show their worth in other domains such as Support, Marketing, and Sales Engineering.

Overall, I found this article very interesting because I was able to get a glimpse into the world of technical communication. Johnson’s blog has helped me understand what is important to the writers and their audiences. This new awareness will help me as I continue to develop my own skills.

 

Tatianna Auguste

Final Blog Post

For our last post we were asked to discuss one of the topics we covered in our course that we thought would be most useful to us going forward into our future careers.  I will begin my new career as a Cardiac Sonographer at the beginning of June.   My job will primarily involve interacting with my patients and acquiring ultrasound images of the heart.  Once these images are obtained I am responsible for analyzing them and creating a preliminary diagnostic report which is then reviewed and finalize by a cardiologist.

I may also have the opportunity to be involved in research in my new position.  This is where I think what I have learned in Techcomm will be most useful.  I would utilize the research methods discussed in this course as well as the persuasive tactics if I were required to present an actual research proposal.  If I were to present my topic to my peers I would likely use visual aids.  They may include posters or info-graphics, and certainly PowerPoint presentations.

This is just one example of how Techcomm may be used, as we have all learned throughout this semester, Techcomm is really everywhere.  The skills we have learned in this course will have practical uses for all of us regardless of our chosen career paths.

~Diana Lynn Schwartz

Final Blog Post on Revising and Editing

     In Technical Writing and Editing, we learned about the four levels of editing: revising, substantive editing, copyediting, and proofreading. Learning about the levels of editing allowed me to get a better grasp at how to approach my writing assignments in class. In the past I have eagerly completed my assignments then struggled to find a rhythm when editing them. More often than not, it lead to me proofreading the paper then submitting it. After being assigned multiple 10-page term papers and numerous other small assignments this semester, I knew I had to find a way to establish a better method of editing and submitting my assignments in a timely fashion. As a first step, I now know to revise individual documents as a whole to establish clarity. If time is permitted, I then update the organization and design of the document. Lastly, I go through the document twice to ensure clarity and consistency and then to catch any grammar errors.

     I believe I have been very successful this semester when revising and editing papers. I not only believe that this strategy is useful while I am still a student, but in the future as an engineer as well. Engineers often write reports, memos, and e-mails to coworkers, clients, and customers. For quick e-mails, it is important to quickly copyedit and proofread to ensure the reader will understand the purpose of my e-mail, however in reports and memos it may be more crucial to go through each level of editing. Knowing how to utilize the four levels of editing is a valuable skill as an engineer.

-Briana Goold