Are Screenshots and Images Necessary?

Hey, look at that! I’m posting in my other blog for once. Careful…the apocalypse might happen before you finish reading this post.

So, this is something that I’ve been meaning to write about for a while: screenshots and images in manuals – do we need them? In my opinion, yes and no: It all depends on the situation. I know that seems like a copout answer, but hear me out on this. Like anything, there is a time and a place for it. Also, being just a technical writing team member might leave the decision out of your hands anyway.

Screenshots and images should enhance the manual and make the steps or text clearer. It’s fair to reason that nearly all users are going to be using the item or software while using the manual, so clear text instructions will usually be sufficient. For this reason, when I’m writing a software manual, I will always include at least 1 screenshot in the beginning chapter outlining the parts of the user interface. This is so users will know where I’m talking about on the screen if I write “In the left pane” or “Select Job Accounting from the main menu.” You’ll notice that nearly all embedded help files in software will be primarily text based, and user manuals seem to be heading that way, too. Since I write software manuals, this is where my personal writing experience lies. For hardware manuals or instructions on putting something together, starting with what is included and labeling them so the users will know to what’s being referred is usually the first step.

I’ve recently had a project manager than I work with quite frequently tell me that he wants all screenshots removed from user manuals for his projects. What purpose could this serve? I believe his reason for this is simply “laziness,” really. I use that term loosely since he’s not the one doing the work, but he doesn’t want any images because that means one of his engineers will have to capture the foreign language screenshots for me when it comes time for translation. This comes down to each screenshot for 7 or 8 languages typically and can add up if you have 10+ screenshots. Honestly, in my opinion, this particular PM has no idea what goes into writing a manual and doesn’t know what one needs to make it usable, but I digress. I had to argue with this particular PM for several weeks to include a few screenshots where I thought they were necessary to explain difficult parts of the UI when different sections dropped down or different areas had the same sub-menu names (this was a very complex piece of software and gave me multiple headaches on a daily basis). He didn’t expect me to be so adamant about it because, quite frankly, in Korean culture, subordinates don’t question their superiors and are supposed to do what they're told without question. Poor guy didn’t know what hit him when he had to work with the only American tech writer on the team that has no problem giving opinions, but that’s for a different topic. The point that I tried to make to him was no matter how intelligent or knowledgeable about the network the users of the software are, they’re learning a new piece of software and will need to know where what I’m telling them to do is located.

Since I’m usually learning the software as I’m writing the manual, I think I have a pretty good idea of where things could get confusing for the user since I’m essentially a new user when I start writing the manual. However, in some situations, your audience might require more than you think they do. I write primarily for enterprise software, so I don’t typically have to worry about general home users trying to use something I’ve written. However, once in a while, I do write a manual for some software included with our SOHO (small office home office) printers. For these, more screenshots might be required since I really need to write for the most software illiterate user that I can imagine. To do this, I try to imagine explaining using the software to my mother, who, poor woman, was one of the most technologically impaired people I’ve ever known and never even owned a computer or a cell phone let alone a printer *fondly remembers many frustrating phone conversations explaining how to use the DVD player or program the VCR*.

With most manuals being provided online or on installation CDs as PDFs, the argument of printing costs doesn’t really hold up anymore. However, if manuals are provided in hard copy, this could very well be a factor – especially outside of the software realm. For hardware, in my division (printers and computers) we also provide hard copy manuals. If you’re across the office trying to use the multi-function printer (MFP) and need to know how to do some tricky copying task, running back and forth between your workstation to consult a PDF and the MFP just isn’t practical. There should, of course, be a manual tucked away somewhere by the machine for quick reference. We also tend to provide installation guides for software as hard copies. Funny story about that really quick for y’all: I had finished writing a manual for some software and it was released. A few weeks later, one of the engineers contacts me and says they need a separate installation and setup guide ASAP since customers have requested it. I asked him why since that information was provided in the first chapter of the user manual. He tells me that users can’t access the manual until the software is installed and set up. O_o Forehead, meet Desk. I didn’t know whether to laugh or cry so I just looked at my teammate and said, “They have got to be kidding me,” and explained the situation to her. She was as confused as I was. Anywho…screenshots and images.

Speaking of hardware manuals or instructions on building something, what about drawings vs. pictures? Drawings. Always. Unless there is absolutely no way to provide drawings, always try to include drawings instead of pictures. You might think that a picture would provide more detail, that isn’t the case. Remember back in your college days when you’re putting together that cheap furniture from IKEA or a bookshelf from Wal-Mart? What did the directions look like? Yup. Drawings. Pictures introduce too much distraction away from what you’re trying to draw attention to. With drawings, you can provide as little or as much detail as necessary and make things sharper than with a picture. If you have to include pictures instead of drawings, try to use as crisp of an image as possible and have them be in color. If you need to provide arrows or markings on the picture, use a color that will contrast well and make things clear instead of more confusing.

So, to sum it up, use screenshots only where they’re needed and sparingly. Using too many will just increase the visual length of the steps and frustrate users: I doubt users will need a screenshot for “Click OK.” You’ll have to really put yourself in your users’ shoes to do this. For pictures vs. drawings for physical items, always go with drawings when possible to make things clearer for your users.

Ya want translation with that?

Translation. Ugh. Remembering to make sure I’m writing in English that’s suitable for translation is probably the bane of my work existence. I would often prefer to be writing something that will never be translated, but since I work for an international company at their HQ, that’s pretty unrealistic. Often it’s not the actual writing that is so difficult – it’s remembering what I’m going to have to provide to the translation company. Honestly, I’d prefer we change companies for this task, but hey, that’s not my decision to make (but I am one of the ones that has to suffer due to the poor choice).

So what kind of a checklist do I try to run through in my head while writing (and later editing) my stuff?

1. Is the sentence structure simple?
2. Am I using active voice? If not, do I have a good reason for it (i.e., active voice sounds wordy or awkward)?
3. Am I using the same words to make the translation easier overall?
4. Am I using the same sentence structure? Repetition = a good thing in tech. comm. albeit boring sometimes.
5. Are the words clear? Any double meanings? Most of the translators are native speakers of the language being translated into and not English.
6. Am I re-using previous content? The translators (supposedly) have a database of some sentences/terms; however, I’ve yet to see evidence of this, but we’ll discuss that later.
7. Have I eliminated un-necessary words (typically when I’m editing other people’s work)?
8. Have I used any idioms or slang?
9. Are the technical words OK to be used and will they translate OK?
10. Do all of my user interface terms match the actual application or device?
11. Is everything labeled properly in Structured Framemaker?
12. So I need to re-iterate something or can I simply provide a link to another section?
13. Do I have any hair left to pull out?
14. Wonder how much easier it would be to have a 1-page manual that just says, “Figure it out yourself!” in every language…

And that’s without having added any images or screenshots. In addition to making sure the language that I’m using is appropriate, images have to be provided in the target language. Those present a whole new headache. Luckily for me, the developers will usually provide these for me. To make their job easier, I try to limit the number of screenshots used in a manual and make the text as clear as possible – especially if the documentation is being provided as a CHM file or HTML. You can imagine how much of a headache this can be if something is being translated into 10 languages – that’s a whole lot o’ screen capturing going on. I also have to make sure that they name the screenshots the EXACT same name that I have for the English versions, so I try to give them a list of these names when I send them a manual to review (note: they never notice and it doubles my work later to provide them a final PDF w/ every single image labeled). Basically, I have to have screenshots for all of the languages provided. If I need to write something on an image, I have to either make sure it’s editable or (and this is what I do usually) just provide a number reference to text outside of the image.

Seems simple enough. Except for a slight snag. Remember that database of terms? I don’t think it exists. I’ve had some issues where I’ve had to contact 3 different teams to ask them for their list of translated terms (e.g., driver terms, software UI terms, and hardware UI terms). Now, in my opinion, if the translators actually had a database of some of our more frequently used sentences/terms, I wouldn’t have to provide all of these various spreadsheets. Also, the terms would all match (which isn’t always the case). Oh the English is the same, but the translated terms can vary depending on who was doing the translating. Anywho, that’s just complaining about our translation team’s processes. So, I also have to remember to gather up any terms and give them to the translators so they don’t have to, you know, translate things...

So, that’s the basic process of what I run through when it comes to getting ready to have a document translated.

Here’s a bonus (not) funny story about screenshots… So I was working on a manual a couple of years ago. It had lots of helpful screenshots. Then came the time for the international screenshots….dun dun DUN!! What do I get from the project manager? A huge, nay, ginormous headache. The screenshots were named as the page numbers they were found on for every…single…image…in…every…language. Maybe 8 languages with about 200 images each? Guess who got to stay in the office overnight and rename EVERY SINGLE IMAGE so we could request translation the next day. I’ll give ya a hint: not the project manager. *sigh* Now when this particular project’s documentation needs to be updated, the PM sends someone else to tell me, and if he has to do it, he ducks and cringes after telling me. But I digress…

Translation is pretty much a necessity in today’s market if you want to do any kind of international business, but it requires a lot more thinking and work than just saying, “Hey, translate this!” to a translator. A lot of extra work and thinking has to be done and red tape has to be muddled through before it can finally become a reality.

Is Outsourcing Worth It?

So…this has been bugging me for a while, and I’m finally going to put my thoughts down in a blog. Outsourcing…good thing if you’re the one being outsourced to, since it can be quite a lucrative business, but maybe not such a good thing if you’re the one doing the outsourcing.
So why does outsourcing bother me so much right now? Outsourcing is best utilized when you need something that isn’t a core function completed. Well, my organization outsources something that I feel should be done in-house by the documentation team: templates. This outsourcing was being done before I came along but will hopefully stop once I point out things to my manager in a month or so. I can understand a small organization outsourcing this as a one-time deal for a universal template. But I work for a multi-million dollar, very large corporation. We have a small team of writers – some are proficient enough to handle the templates themselves. But no. We’ve outsourced this. Enter me. I start using the Structured Framemaker template and start noticing all kinds of usability issues and things that we need to have changed to make it work for more than one manual type. I see documents as living things – they should always be evolving and improving. This becomes too expensive if it’s being outsourced and you’re charged $200/hour. It’s much more cost-effective to have someone in house that is a document design specialist/writer/editor/whatever that you can utilize to make changes when necessary. The other problem comes down to translation issues: templates also may need to be created for other languages – specifically those that read from right to left. So let’s say I need to have a template modified for a completely different scenario and the outsourcing company says it will take 2 days of work at $200/hour to accomplish – that’s a whopping $3200 for a 2-day venture. If you have to do this a couple of times a year, you might as well invest in your team and pay for the proper tools and training so you can do it yourselves. I would think investing in your employees would be a way to improve team morale and documentation quality.

So that’s my current negative rambling on outsourcing. To sum it up: I don’t think outsourcing template design when it can be done better and cheaper in-house is a good idea (when you have your own team of writers that are capable. It limits the writers too much when things can’t be modified and the documents can’t evolve to meet the changing industry and customer needs.

Articles? I don't need no stinkin' articles!

This is an article I submitted to the TechCraft E-Newsletter, so I thought I'd also post it as a blog entry.

Sometimes I wish the English language didn’t use articles. I also wish I had hot keys for a, an, and the on my keyboard. At my previous teaching position for a hakwon (after school academy) and my current position with a Korean company, articles were and are the bane of my existence. These simple words that native speakers take for granted seem to make up half of my editing tasks.

Even though my position is technically as a technical writer, I also handle the editing for my small tech writing team (3 members total), the manual team, and random software UIs. It’s a delicate balancing act to make time to do my own writing and edit everybody else’s at the same time to ensure we all meet our deadlines (especially since Koreans are famous for I-need-this-in-5-minutes assignments). So how do I attempt to catch all of the article issues and everything else (hopefully) quickly?

Meet with the writer

If the document is over something I’m completely unfamiliar with, I’ll meet with the writer before I start looking over it. This allows the writer to give me a quick overview of topic and who the audience is going to be. It also gives the writer a chance to tell me about any known issues in the document.

Give the document a quick once-over

Before I start any in depth reading or making any major changes, I’ll typically print out a hard copy and skim through it looking for any glaring formatting errors (e.g., formatting changes, figure labels, alignment issues) that I might miss if I’m editing on the computer screen.

Read through the document multiple times

I’ve found that if I try to split my attention between content, readability, grammar, etc, I usually miss something. In order to try and prevent this, I read through the document multiple times and try to focus on a different aspect each time.

One of the things that always drives me absolutely crazy while reading is grammar errors: I read through the document the first time and try to focus on only those problems. Since the writers are non-native English speakers, this tends to become the brunt of the workload…with most of that spent adding in/removing articles. Sometimes that can be quite a challenge for me as well since sometimes I’m not sure which article to use myself and have to leave a comment for the writer asking for clarification.

The second time I read through the document, I try to focus only on the content and if it will be understandable to the expected audience. Because of the Korean culture (low-context), I tend to find myself constantly asking for more information since that’s expected in the Western world. We don’t like guessing. Ambiguity and uncertainty can lead to mistakes/errors which in turn could lead to trouble for the company. If I could possibly misinterpret something, the reader could as well so I ask the author for clarification.

Also, since I work in R&D HQ, these documents are used as the basis for translation into about 30 languages. To make sure we can get the clearest and best possible translation, I try to make sure only Simple English is used and all idioms or slang have been removed. It might seem strange that non-native speakers would use these, but Koreans are taught idioms during their English language study. Also, oftentimes, the engineers they are working with have studied abroad and might use slang/idioms during the SME interview.

Take breaks

Let’s face it, editing isn’t the most thrilling thing in the world to do and can also be frustrating when you find yourself correcting the same things over and over again (“Find and Replace” in Microsoft Word works wonders for this sometimes). I try to take breaks every hour or so, when I find myself mindlessly scrolling down the document, or when I have to re-read paragraphs multiple times. If it’s not a very big document, I might just walk away and get a cup of coffee, or work on something else for a bit. If it’s a large document and I have time, I might take a half a day break from it or a few hours at least. A bored and unfocused editor doesn’t do anybody any good.

Pass it back to the writer

After I think I’ve caught everything, I send the document back to the writer to review and make changes. I also ask the writer to please make sure to send it back to me again for another review before finalizing the document. Sometimes this final review process can take a long time to happen. The writers tend to go back to the SMEs to clarify something or just to drag more information out of them. Also, since the writers aren’t native speakers, sometimes we have to meet to go over the comments I’ve made or just so I can explain why I’ve made some of the suggestions/ changes that I’ve made.

I tend to be a perfectionist and want my division to produce the best documentation possible, but I have to remind myself that nobody is perfect and sometimes I can’t remember a particular rule or question changes I make. To help combat these issues I keep Technical Editing (Fourth Edition) by Carolyn Rude on my desk at all times. Editing documents written by non-native speakers can be frustrating at times but also very rewarding. I like to think that they learn something each time I pass a document back to them and that makes the “article headache” worth the pain.

Advice for Tech Com Students

I was recently asked for advice on landing a job in tech comm by a student at my alma mater. I'm probably the last person in the world to be giving advice on this topic, but I'm always willing to give my opinion and hope that it helps someone.

I'm currently working for Samsung Electronics in Suwon City, South Korea so my U.S. job hunting experience wasn't that successful ;). But how did I manage to land a gig with a world-wide company at their HQ? Networking. While I was teaching English here, I met a fellow tech writer online (my buddy now: Rahul Prabhakar) that works for another division, interviewed, and was probably going to be hired. That position fell through (reorganizing and all that jazz). But then I met a manager while on an island trip and the rest is history. I was in the right place at the right time and met the right people. Don't be afraid to talk to people and sell yourself. It also helps that technical writers are nearly impossible to find in this country (ROK)...let alone western ones. So how can this help you find a job in the U.S.? It can't. But the advice to network still stands. Oh, another networking tip (other than taking island trips in Korea) is to join listservs. Listservs are a great way to meet people in the field and get advice and stay caught up on trends.


My experience in job hunting in the U.S. was very difficult. It's a Catch 22: employers want you to have experience, but nobody is willing to give you that experience. If you can find a niche field to work in and become knowledgeable in (e.g. some medical area, a specific area of IT), it will also help your chances. Most employers expect to spend 3 - 6 months training you anyway so they are more concerned with your writing ability and capability to understand technical ideas and break them down. However, sometimes your writing will be for people that are more knowledgeable than yourself in an area. For example, right now I'm writing stuff for Java developers. Am I a Java developer? No. Can I understand it enough to write it and organize it better than our Java developers? Yes. Bottom line is employers looking to hire junior technical writers want to know that you have the ability to understand things and play well with the engineers (SMEs).

Being able to use the tools currently being used in the industry is a bonus that employer's will definitely consider. Adobe's Technical Communication Suite is a good place to start. Microsoft Word and Publisher are 2 more that are handy to have experience with. Then there are things that you probably won't get experience with in the classroom and will have to explore and play with on your own: DITA, XML, etc.

The next piece of advice is be able to write correctly. If you are hired as a junior tech writer, you will have an editor at your disposal. However, still do your best to use correct grammar and punctuation. I personally don't have that luxury ( I am the editor) so I keep reference tools within reach to check myself and make sure all of my documents, and other people's, are correct.

Next, get experience. Try to get as much experience in as many areas of the field that interest you. Getting an internship would be ideal, but might not be feasible. Offer your services online. Freelancing positions can be difficult to acquire, but will be good experience if you can land them. Do projects with your university. If you go to my old uni, University of Missouri - Rolla (now Missouri Univesity of Science & Technology), you have a whole world of opportunities open to you since it's known for its cutting-edge research and patents.

My last piece of advice, and arguably the most important, is to not give up. Hang in there: something will come along. The current economic situation in the U.S. and worldwide has meant fewer new jobs opening up overall. This also means that companies are going to want to get their money worth. Why hire a green person and invest time and money into him/her when the newbie will just leave in a couple of years anyway for a better paying position elsewhere? They'd rather hire someone that has experience and will stay with the company for 5+ years.

So....there ya have it. That's my advice: network, get experience, learn as much as you can, write well, and DON'T GIVE UP. Take it or leave it, but I hope it's somewhat helpful.