Check out this new episode of the 10-Minute Tech Comm podcast featuring Larry Kunz of Leading Technical Communication. The episode features some great advice about working with and interviewing subject matter experts!
When words come unstrung: The Catastrophic Failure of the Martin Archery Jaguar Take-Down OWNER’S MANUALPublished November 10, 2014 Uncategorized 2 Comments
The minimum requirement of any good technical document is that it communicates what is required of the user in a clear, concise, manner. Yet, far too often, technical manuals bear a striking similarity to experimental poetry, where the meaning is known only to the author. Peter Vogel once argued that users typically refer to the manual only when they are already frustrated. While this is certainly the case, I would further posit that on occasion, the source of the user’s frustration can be the technical manual itself. Case in point: The Martin Archery Take-Down Bow OWNER’S MANUAL.
To be fair, the exploded view of the bow on the front page of the four page manual does offer clear instructions for assembly. The diagram accurately represents the parts and assembly. The clear directions listed here allowed me to quickly assemble the body of the bow without incident. However, that is only half the task. A bow without a string is little more than a piece of furniture, which leads me to part two.
Stringing the Bow: Where it all went wrong
Page two of the manual features a paragraph entitled “Stringing your Bow.” Martin Archery included a (rarely included) tool called a bowstringer to assist with this task, promising that its use would prevent the limbs of the bow from distorting. The manual offers a lengthy paragraph extolling the virtues of the bowstringer. What was conspicuously absent was any text informing a first time user as to how to effectively use the bowstringer. Instead, there is a drawing that a stringer being used, devoid of any further instruction:
Attempt one: I placed the stringer on the limbs of the bow, and then slipped the loops of the bowstring itself over the limbs after the bowstringer. I followed the procedure outlined in the diagram, and it worked—for all of three seconds. The stringer caused the bow string to slip from its grooves. Once the tension was released, the limb of the bow de-flexed, colliding with my ribs. After no small amount of profanity, I moved on to
Attempt two: A few of the more crucial portions of the legal action of Wile E. Coyote vs. Acme Corporation echoed in my mind, as I attempted once again to string the bow. This time, I wound up with the string dangling loose inside of the now taut bowstring. This was problematic because an arrow could potentially tangle in the stringer.
Attempt 3: I placed both the bow and the stringer on the limbs of the bow; then I placed my foot on the stringer. I tugged upward, just as the diagram suggested; this time I wound up with the stringer dangling loosely from the top of the bow with the other end secured to the top limb. At this point I gave up and consulted this YouTube video:
In the space of less than a minute (the video shows how to string and un-string the bow, I paused after the first part), the YouTube video successfully demonstrated, how to quickly string my bow. While the manual was lacking in terminology and proper instructions, the video named each part of the stringer and where to properly place the stringer in relation the bow, demonstrating that the stringer does not “tow” the string into place, but rather bends the limbs of the bow allowing the user to move the loose end of the string to the notches while keeping tension on the body of the bow rather than the bowstring.
The Martin Archery Take-Down Bow OWNER’S MANUAL stands as a cautionary tale of how technical writing, when done poorly, can be hazardous. A lack of clear verbiage accompanying the diagram, which would inform the reader on where to place the parts of the stringer and how to use it properly, resulted in frustration and lost time. This could have easily been avoided, had the writers applied the same care and attention to detail in crafting the instructions for stringing the bow as they did for its assembly. At the cost of perhaps another page of text, the writers could have added more diagrams, or at the very least, step by step instructions for where to place the stringer in relation to the bow. Additionally, it would have given the user the all important detail that the body of the bow is to be bent, releasing tension on the bowstring, rather than trying to, by physical strength, pull the string into the notches. Had such measures been taken, Martin’s client would have experienced far less frustration, and it goes without saying fewer bruised ribs!
Tags: " "technical communicator
The UN and the World Bank says that 10% of everyone in the world has a disability of some kind. That is a lot! And in addition to that when we get older, over 30% of us will have some disability. These numbers show that thinking about accessibility when writing and designing our content is extremely important. The first questions that should pop up in our heads are: Will my audience find what they need? Understand what they find? Act appropriately on that understanding? There are many reasons why people have trouble reading: cognitive problems, low literacy, physical or vision disabilities, or reading in a second language. But even proficient readers can have problems reading if they are rushed, stressed or tired. You should write in plain language and present your content clearly and flexibly to make it accessible. But how can you do so? Here are some useful tips:
Think about your audience first
Know your audience and make your content suitable for them. You should know what your audience needs. Writing in plain language doesn’t mean dumbing down the content, but making it clear by getting straight to the point.
Keep in mind that not everyone will read every word you write. People are usually in a hurry or multi-tasking. They also read in places that make reading difficult such as poor lightning or on electronic devices with tiny screens. Your content should be easy to scan through! Use topic sentences to introduce the subject of your paragraph before going into details. Also, keep sentences short and concise: avoid the passive voice and use simple and clear verbs.
Your content should be easy to translate
English is the international language. Many readers are non-native English speakers. Make your information easy to translate. Write simply by using words that your readers will be familiar with.
Use lots of headings
Create meaningful headings for each section. Useful headings should communicate the key points of your content, helping readers scan and find the information they need. They can be questions, statements or topics.
Talk to your readers
Get personal and talk directly to your audience. Talking directly to your readers makes a better conversation. People tend to pay more attention if you are referring directly to them. Use “you” and the imperative to give readers instructions.
Put the sections of your content in a logical order from your readers’ perspective. Start with the information they need first. Use bulleted lists or tables to make it easy for them to scan through your text and find specific information.
Many people understand information better through images. Use images that illustrate concepts and give them an alternative text or captions. Information graphics and animations showing processes and relationships are also very helpful.
For more information, check out:
Source: Horton, Sarah, and Whitney Quesenbery. A Web for Everyone: Designing Accessible User Experiences. Print.
So you’re looking for a job and you’ve just completed your resume, and it’s looking good: the formatting is right, it’s concise, and you’re pretty satisfied until you get rejected for job after job. What’s the matter? Well, you have not framed your resume, and I don’t mean mounting it on your wall in a picture frame.
Framing is a technique that is most often used in media, marketing, and politics. It is how newscasters get you to view a certain story in a certain way, how companies convince you to buy their products even though you don’t need it, and how politicians get you to vote for them even though you don’t agree with them at all. Sounds a lot like manipulation, yes, but it is useful. Framing, in technical and more positive terms, is the rearranging of content so that the writer emphasizes what he or she wants the reader to focus on. This is one of the most crucial parts of resume writing, and by this I mean arranging and rearranging the content of your resume so that you look like the best candidate.
When framing your resume the most important thing you can do is research the job and the company.
Do Your Research:
Know the Job
You need to know something about not only the job but the employer. Not all technical writing jobs, for example, are the same at every company. The first place to check, of course, is the requirements section on the job listing and cater your resume to that company’s requirements. You should also pick and choose which of your other qualifications or past jobs could boost your resume a bit. But, do not include that one summer when you worked as a counselor at a day camp because if it is not relevant to the job you want it will not help you, and it will clutter your resume.
Know the Company
While you should check the requirements on the job listing, you should also get to know things about the company that are not on the job listing, for example, do they use the agile method, or are their technical writers expected to sit alone in an office in the back near the bathroom. Your resume could play up to this. You could emphasize the jobs you had where teamwork was encouraged or emphasize those jobs where you were expected to be productive without much overhead. Or add them both to show that you can work in any environment because you’re flexible.
Once you’ve done your research and you know the job and the company you are ready to frame your resume and essentially sell yourself which is what any good resume attempts to do. The thing to be sure of is that you do this for every job because the most important aspect as I have explained is knowing the audience. Even if you are applying within the same company your audience can still change so be sure to frame your resume specifically for your audience each time. Happy job hunting!
For more information visit:
There’s a high probability that entry-level technical writers will work in an agile environment on a scrum team. Many companies, especially software companies, are adopting the agile model. Agile is a way to involve more people from different areas of expertise into a single setting when developing a product. The basic idea is that team members will have more efficient communication and input through various stages of project development than they had before being placed into agile teams. Scrum groups are usually comprised of the product owner, the development team (3-9 individuals of cross-functional skills), and the scrum master. The overall objective of an agile environment is to create a better product and increase revenue for the company.
New situations can be intimidating. If you’ve never been a part of a scrum team or worked in an agile environment, you don’t really know what to expect. Sure, you can do some research and be somewhat aware of what a scrum team is and what it does, but you don’t have experience until you’ve been a part of a scrum team. Besides researching, what else can you do to prepare yourself? You can start by practicing good manners and etiquette.
Before stepping foot into your first agile or scrum meeting, even if you’re not sure what to expect, you can still prepare yourself to make a good impression. The following are five tips to help you do this. There are several other ways in which you can display good manners and proper etiquette in the workplace, but this is a good place to start.
1. Electronic Devices
If you bring an electronic device into a scrum meeting, use it in an appropriate way and at appropriate times. Make sure your phone is on silent. If you get a call, don’t disrupt the meeting. I’m not referring to emergencies here. There are times (sick child, accident, etc.) when you must take a call. Don’t text. Save that for after the meeting and after work is over for the day, if possible. If someone is speaking to you, don’t have your nose stuck in your device. Look them in the eye and pay attention. There aren’t many things more rude or annoying than trying to have a conversation with someone while they’re lost in a cell phone or iPad.
It should go without saying that in professional environments one should dress professionally. Most companies usually have a dress code or standard for employees. If the dress code is outlined in an employee manual, the guidelines for work attire will be clearly defined. Sometimes, however, the dress code can be less formal. If the latter is the case, pay attention to how everyone else is dressed and follow their example. Avoid clothing that is too revealing. You want to present yourself by the way you dress as someone who is ready to work, not someone who’s ready for a night at the club.
You’re the new guy. This is your first scrum meeting. Don’t try to impress everyone with the world-changing idea you have for the company. There’ll be time to share that later. Listen. Pay attention. Take notes. Learn.
4. Unnecessary Noise
Because this is your first meeting, chances are you’re going to be nervous. Anxiety affects people in different ways and at different levels. Some people seem to never get nervous in any situation. For others, anxiety can be crippling. Be careful to not make any extra noise that might distract others. Tapping a pen on the table, making audible noises with your mouth, tapping your foot on something, etc., all of these can be very distracting to some people. Be aware if you do these things when you’re nervous and make a conscious effort to avoid such habits.
Be at least five minutes early to the meeting if you can. If the meeting starts at 9:00, don’t be walking in the door at 9:00. That would make you late. The meeting might already be in progress at that point. You could be a distraction if you’re jostling around for a seat while everyone else is already settled in. Arriving early will give you a chance to get acclimated to your surroundings and will help you relax.
How not to conduct yourself in a scrum meeting
Remember when your high school teacher assigned a group project? You didn’t mind as long you got to pick the members of your group. If your teacher picked the members, then you knew it was a recipe for disaster. You hoped that at least one member of the group would be the quintessential over-achiever, that person who always had to make the perfect grade and never settled for less than perfection. That would’ve been a bonus. On the other hand, you could virtually be assured that at least one person in the group would be the lazy guy who never did anything in class. You could always count on that guy to do absolutely nothing. But the one person, above all, you did not want in your group was the guy nobody got along with. He never listened to anything anyone else tried to say. He bullied his ideas into being accepted by the group. He showed up late for assignments. He made the whole project unbearable and unproductive. Don’t be that guy.
Links provided if you want to learn more about proper etiquette and manners in business meeting environments. A general business meeting isn’t the same thing as a scrum meeting, but the settings are similar.
Tags: program information, Software
Who said that coding is a man’s job? If you haven’t heard, the new trending topic is #girlscodetoo. A novice may ask, “What is coding?” CodeQuest.com simply defines coding as “what makes it possible for us to create computer software, apps and websites.” In fact, all of the technological devices that we depend on exist because of code. This includes, “your browser, your OS, the apps on your phone, Facebook . . . they’re all made with code.” In the last several years, the push to promote science and math education amongst girls has heightened. It is believed that the earlier we can get girls to embrace science and math, the more well-rounded they will be and better prepared to compete with their male counterparts.
WHY IT MATTERS
In middle school, 74% of girls express interest in Science, Technology, Engineering and Math (STEM), but when choosing a college major, just 0.3% of high school girls select computer science. (Image and information taken from GirlsWhoCode.com)
Teaching girls how to code is one of the ways organizations across the country are showing that it’s past time to close the tech gender gap. For those girls who want to take on the challenge, there are countless opportunities to get their code on. Last summer, the University of Alabama-Huntsville hosted the first Tech Trek in the state of Alabama. Rising 8th grade girls from across north Alabama were invited to attend a week-long residential Science, Technology, Engineering and Math education (STEM) program. During the program, campers created cell phone apps, built robots, and learned about engineering design among other things.
Tech Trek is not the only program aimed at promoting the desperate need for girls to enter technological based fields through learning how to code. A quick google search using the words “girls code” will bring up countless organizations that are now in the race to teach girls how to code. One of the most popular groups is Girls Who Code. The founder, Reshma Saujni proudly states, “This is more than just a program. It’s a movement.” In fact, major corporations like Google who has initiated its $50 million dollar Made with Code program recently donated $190K to another group, Black Girls Code. The purpose of the donation is to provide money to support the code training of minority girls. The movement is indeed growing.
Ironically, girls are not only the targeted audience. Women based groups are also hosting programs to teach women how to code as well. Once again, Made with Code has allotted money to pay for thousands of these women to attend Code School, an online web training school. If these initiatives are successful we can expect to see a large increase in females moving towards careers in Engineering, Software Coding, Technical Writing and Computer Science.
If you or a girl you know are interested in learning how to code for personal projects or to advance your own career here are some helpful pointers:
- Locate one of the many groups that cater to teaching women (there are monthly workshops and summer programs happening all across the country).
- Find online coding programs and tutorials from groups like Code Academy and Khan Academy (both are free).
- Enroll in boot camp coding programs in your area (you can receive one-on-one instruction but you will have to pay a substantial fee).
- Enroll in university courses (take programming classes in the university setting).
Anyone can code and be successful at it! You’ll be proud that you learned a new skill. C’mon girls of all ages. Let’s start coding!
Tags: technical writing, writing
Imagine the following scenario and ask yourself: how many times have I been in this position? It’s almost midnight, the night before your term paper is due, and you’re stressing over the last minute details. All the information organized in a logical way? Check. Correct spelling and punctuation? Check. Sources cited properly? Check. Then you realize…“oh no, I still haven’t written the conclusion!”
Raise your hand if that sentence has passed through your head at one point or another, because let’s face it, writing a conclusion is a pain in the neck. Whether it’s a short paper for class or your first proposal after starting work at a new company, the conclusion is always the section of the paper that you put off writing for as long as possible. Seriously, how are you supposed to sum up, say, your 200-page dissertation in just a few paragraphs?
1) Ask the question, “so what?”
Your conclusion shouldn’t ask and answer the question, “what is this?” Hopefully, the rest of your paper has already done that. Rather, ask the question “so what?” meaning ask yourself, “why is this information important and why should anybody care?” This is particularly effective if you’re a technical writer finishing up a document; you’ve just spent x amount of pages describing your product, but it won’t do much good if the audience is still unsure about buying it. Use this as a chance to make them sure.
Use the Socratic Method when thinking of how to form your ending statements. Play out a little dialogue in your head between yourself and the potential reader. If the reader asks why your argument is relevant, have a definitive answer ready and waiting. If the reader picks out a flaw in that argument, find a way to back it up. Remember, your conclusion is your last chance to make the audience realize why your points are valid. Make it count!
2) Restate your thesis.
This is where things can get tricky. First of all, reiterate your thesis, but don’t say exactly the same thing you did in your introduction. Find a way to rephrase the original statement, including some examples previously used in the paper. Synthesize your main points and show how they form a cohesive argument – explain why everything fits together. Think of your paper as a jigsaw puzzle and your conclusion is the final piece that anchors the rest of them. In doing so, you are able to not only sum up your points without being redundant, but also show your audience that you care enough about your argument to give it a good ending and not take the lazy, copy-and-paste-the-original-thesis approach.
3) Connect the topic to broader themes
This is a good way to get your audience involved in the discussion. Ask a question about your topic and then propose a solution, apply the information to something else of relevance. For instance, if you’re writing an analysis on The Adventures of Huckleberry Finn, then give examples of how that novel has influenced others in contemporary American literature. Likewise, if you’re writing a scientific paper, then elaborate on how the discoveries made could impact future studies. Make your audience think about how your argument connects with others like it, and in doing so, potentially discover the topic for your next paper.
And there you have it, folks: three steps for how to write an effective conclusion. It’s one of the hardest and most nerve-wracking things to write, especially if you’re a proposal writer and any part of the given proposal could determine whether or not your company gets the bid. So bear these tips in mind the next time you sit down at your desk at midnight the night before the assignment is due. Because to your teachers, the idea of a weak conclusion is totally and completely…
For more information, visit http://writingcenter.unc.edu/handouts/conclusions/
Thanks for reading!
Erin S. O’Reilly