A Focus on Structure

I believe that of all the topics covered in this class, I got the most use from learning about structure. I already knew to use appropriate language and give consideration to the audience, but I didn’t know how important structure would be in a document. A nice structure will lead to a nice outline, a nice outline is just filling in blanks. This only works for some documents, but structure is important regardless.

I will adopt this newfound appreciation for structure by spending more time focusing on it prior to starting to document. I will also be willing to revise the structure to fit the content if necessary – you can’t fit a square peg in a round hole. I see this helping me in the near future because I intend on writing many different kinds of documentation – processes, use cases, alerts, and config files are all things I believe I will be documenting this summer. Having a defined structure for each, and a way that they can all fit together (this is for a single project) will be fantastic when trying to write the documentation.
~Connor Shade

Advertisements

Importance of Plain Language in Information Technology

Honestly, I have learned a lot in this class and they have all changed my writing skills in one way or another. A couple of most important things to remember is to research your audience, keep the piece clear and concise to capture a wider audience, and try to use visuals to capture the interest of readers. I learned new ways to start writing a document, like logical mapping which I have never used before. I learned the different types of documents and which situation demands what kind of solution. I currently work for Information Technology Services at RIT, and if there’s one thing I have learned, never assume what the front person may or may not know. I realized that many end users, irrespective of their technical knowledge, prefer visuals to understand something. For instance, if a user is trying to map a printer, they would rather have visuals (screenshots) showing them an example, instead of just a set of instructions.

Plain language is pretty important in my profession, mostly because people have varying levels of education and technical knowledge. Another thing to notice is that the kind of language you use will vary intensively from how you communicate with your peers, for instance systems administrators and security analysts to name a few, and how you communicate with end users. One rule that has helped me a lot is if you do not know the person at the end of the line, start off with as simple plain language you can, and work your way up to more technical terms if you deem the person has that knowledge and expertise. I sometimes help someone who has performed all basic troubleshooting I would have performed to find what is wrong, and this tells me that the user at least has some technical knowledge.

Overall, using plain language can sometimes be as effective as using very technical terms in order to get your point across to the reader. This class has helped me a lot in honing my writing skills.

– Smayan Daruka

The Importance of Structure

The structure of a document is the foundation upon which its information stands. This is something I learned in this class that changes how I approach work.

I see structure as something that can be implemented just about anywhere. Knowing that it is important for Technical Writing is a bonus, but the real benefit is that any area can be improved with structure. Structuring a to-do list can make it easier to read and act upon. Structuring files can make finding things quicker and easier. Structuring your day can improve your productivity. Structuring free-time can even improve the quality of this time (I read this a long time ago, it was a newsletter from Cal Newport I think). Structuring your day can improve the amount of work you can do (Cal Newport writes about this more than anything else I’ve seen: example).

This relates to work in the following manner: Structure, whether in writing or in life, increases the return on investments. Having a structure for writing will make the work easier to perform. Scheduling may take some time, but knowing the order you want to put things in beforehand will make writing them down easier. Structure also makes reading the writing easier – people like a structure in what they read. This is why books have a plot that normally follows a basic outline. Reading chapter 13 before chapter 3 will leave you confused. Some writing can still take this form, but hopefully using structure will prevent this.

~ Connor Shade

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

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