Word Tip: Inserted Picture in Word is Cut Off by Preceding and Following Paragraphs

A coworker asked for my help with this issue. He was working in a document that he had received from someone else. He placed the cursor in front of a paragraph, pressed ENTER, then inserted a picture. He could see the outline of the picture when the picture was selected, but only a small piece of the picture appeared in the line where he had placed it:


He checked the picture layout (i.e., Text Wrapping > Behind Text), and everything was fine. Then he asked for my help.

I selected the paragraph into which the picture was inserted. Then I opened the Paragraph dialog box to check the line spacing:


The Line spacing was set to “Exactly 12 pt” which means no matter what he did to the picture, it was only going to show exactly 12 points of it. Changing the Line Spacing to “Single” allowed the entire picture to appear:


Why did this even happen? For some reason, that document’s “Normal” style had line spacing set at exactly 12 points. There really is no reason for this in “regular” documentation. If you were doing something fancy with layout, you might want to adjust the line spacing. But plain old “single” spacing is usually fine for most documents, and that line spacing will adjust automatically depending on the font size. (The same reason that you do NOT have to double space after a period!)


“This product is awful” usually means you can’t figure out how to use it

Documentation not only needs to educate your customers and provide on-the-spot troubleshooting assistance, but also can be used as a sales tool and a revenue generator. I’ve never been a fan of putting marketing-speak in technical documentation—that’s not what I mean by “sales tool.” What I’m saying is that providing good documentation allows prospective customers to more accurately ascertain whether your product meets their needs. With up-to-date online documentation, a prospective customer can quickly find the information he needs on his own. If your documentation doesn’t provide enough information, potential customers will find a vendor who does. A thoroughly documented product also gives the impression that the product is easier to use than your competitor’s, whose product documentation was written one Sunday morning by a developer needing to meet a release date. Good documentation before the sale gives the customer faith that the documentation after the sale will be as good. Companies that are consistently the winners in their industry care about educating their customers and prospective customers. Failure to properly document your product creates an opening for your competitor to capture that customer.

When someone says “this product is awful,” what they usually mean is that they can’t figure out how to use it. If they attempt to use poorly written documentation to figure it out, they are even more convinced that the product is bad. Good documentation results in happier, loyal customers and reduced customer support costs; customer support can spend more time providing higher value service and less time “hand holding” capable customers. Sure, good documentation can be expensive; but according to Forrester, the average call center call can cost a business as much as $50 per call. For technical issues, costs per support call can be as much as $150 per call. If customers can use the documentation or an online forum to solve their problems, the average cost is usually less than a dollar. In fact, Forrester’s research indicates that the average is about 10 cents per customer.

Most companies gather statistics on how many support calls are generated in a day. Based on the high volume of calls, they assume that the documentation is not being used. They fail to note how much customer support uses the documentation to help the customer. A large percentage of customers would rather call support, ask a specific question, and be told exactly what to do to fix their problem. This type of customer will never use the documentation unless they have to pay for phone support. Online help that allows the customer to provide feedback can provide statistics regarding not only how many people actually read that particular help topic, but also can tell you whether customers think the information is useful or a waste of their time. (Microsoft Support is a good example of this.) Product managers can use that feedback to improve the product and the documentation.

Some help documentation tools and formats allow for user feedback forms (“Web 2.0”), but having the ability to type comments into a form on a help topic is not enough. You also need a connection to a server that can store the feedback. With the right software, you can also view and print reports of which topics are used most often and what the comments are, which can tell product managers which areas of their application might need improvement to make it easier for users to understand.

Even though the products that I document use in-application help, I also provide online, web-based help. In that help, I could easily create a web form in which anyone who visits the topic could rate the topic and add comments that could improve the topic. Their comments would be visible to other users of the topic and, most importantly, to me. I could use their comments to improve the topic and the product manager could use their comments to improve the product. However, I don’t have the application that I need to manage the comments, store the comments, or report on the comments. Many companies won’t allow you to use a product that has a user feedback system or want to spend time creating their own automated user feedback system. So the best you can hope for is a user forum or a knowledgebase tool that allows user feedback, but that’s a manual system, doesn’t provide for reporting, and doesn’t tell you whether your help documentation is helpful or confusing.

One day, “Web 2.0” help with be the norm. For now, just keep plugging away at your help and hope that the feedback you do receive helps you improve your documentation.


Why does documentation "suck"?

One of my tasks for slow periods at work is to troll the User Forum to read what our customers are having problems with. Each time we release a new version, there are plenty of posts to keep me busy. If I had any sort of ego, I would be severely depressed reading some of the posts that say “the documentation sucks”! OK, it doesn’t happen often, but it happens. And almost every time I read or hear that, I can point the complainer to the exact topic that they didn’t bother to read before stating that the documentation sucks. Yeah, you are correct—the search sucks. It’s not Google search. And yes, when you call tech support, we have a great group of guys who can hold your hand as you walk through the tedious process of creating a chained certificate. But before you blame the documentation, at least make an attempt to read it. All of it! Scroll through the Contents or Index, or type text in the help’s Search box (NOT GOOGLE) and press ENTER. That word got no results? Try another one! Read a few results to maybe clue you in to what words you should be using. Try those words. Read a few topics. You might learn something. You won’t waste your time, because next time you have a problem, you might need that exact information.

Why does documentation “always suck”? Below are several reasons:

8) Too many cooks in the kitchen. You’ve hired a technical writer who is both technical and a writer (yeah, doesn’t always work that way), and yet everyone wants to tell her how to write. Let her write it. She knows end-users better than you think and has experience writing to that audience.

7) Several different locations are available from which the end user tries to get help: in the application, online, PDF, knowledgebase, user forum…and that’s just the locations we can control! Something is bound to get lost in the shuffle—or too much salt added to the soup, to continue the “cooks” cliché.

6) Companies like to save money. Why would they hire a highly-paid programmer to spend his day writing documentation? And if he’s a programmer, why would he want to? Besides, developers tend to be very advanced in their field and talk way over the customer’s head. (“Everyone knows that!”) The customer wants to know “what grade of oil should I use in my car this winter?” not “how does the internal combustion engine work?” (Note: I have met programmers who write very well to an end-user audience. But they are rare. Many write “to please the teacher” rather than to have their communication understood.)

5) Companies like to save money. They are likely to hire “Bob’s cousin, Milly who’s really good with Word” as their technical writer. Sadly, Milly barely knows how to lock her keyboard, has never used a help-authoring tool, and certainly doesn’t know how to install beta, undocumented software on a virtual image. The developers then, begrudgingly, write most of the documentation—-which is way over the head of their customers and Milly.

4) And by the way, companies like to save money. They often hire someone who not only cannot install and use beta, undocumented software on a virtual image, but also cannot write complete, lucid sentences. At those times when the technology is way over her head, a good technical writer can identify the nouns, verbs, and objects in the sentence, put them in the correct order, and actually make sense of it; or she can bug the developer until he explains it to her in plain English.

3) Developers are busy and don’t want to document how to use their product. “Why, my product is very user friendly and intuitive! We don’t need a user guide!” This is where the technical writer’s interview and annoyance skills come in handy. A developer will eventually get tired of her questions and actually provide helpful information to a technical writer. (He would just blow Milly off, because she wouldn’t understand anyway.)

2) Sometimes (OK, usually), the release cycle is more important that the documentation. The documentation is delivered and signed with help content that is a week or more old. (A lot can change in a week of QA!) In my case, I update the online help and knowledgebase as new issues come to light. (See number 7.) But I’m occasionally left out of the change loop.

1) And finally, the number one reason “documentation sucks” is that it sits unused. The customer doesn’t want to “bother” to read the whole user guide, which could be thousands of topics. Average Joe Customer wants to click Help and have a window appear with a hand that reaches out from the monitor, types the information that he needs to specifically answer his question, and pats him on the back, telling him it will be OK. Dream on Joe. You have to work harder than that.

Here are a few Frequently Asked Questions about Help documentation:

Why did you put THAT in the help? Everyone knows THAT!
Nope, sorry, Mr. Engineer, but not everyone knows how to find the capacitive reactance of a parallel circuit, even if you think it’s a prerequisite to using our product. While we’d like to believe that everyone who uses our product is at least as smart as you, the truth is, we aren’t.

Why didn’t you put THAT in the help?
Because I document *our* product, not Microsoft’s, Oracle’s, and Java’s. Granted, there are some situations that warrant repeating information from their help in our product’s help, such as when configuring their product a certain way will make our product not talk to their product. But they have their own technical writers who have worked hard to make their help available to you at publicly available links, so you should use it.

Why can I never find anything in the help?
Let me state this as kindly as possible: you don’t know how to search. Before computers, searching talent was reserved for librarians, and we counted on them to find things for us. (Inside every good technical writer is the heart of a librarian.) Now we count on Google to find things for us. Sadly, Google has not penetrated every database in the world—yet—so until they do, we must use our own search skills to find the information we need. And, yes, it can be a challenge at times. If you have honestly searched every possible search word you can think of to find what you want (e.g., script, bat, VB, batch…) and still can’t find what you need, send an email to the technical writer of that Help documentation or the product’s user forum and say “I searched for “X” in the help using these terms ‘blah, blah, blah’ and couldn’t find it.” Then I can add those key words to the relevant topics so that next time you will be able to find the right topic. Another point: the application’s Help is written for the average user of that product. If you can truly “never find anything” then perhaps you are an advanced user and should instead search the knowledgebase or user forum, or call technical support?

How can I read the help before I install, if installing the product installs the help file?
GOOD question! I’ve been asking product managers that for years. Well actually what I ask is, why do I need to include installation instructions when no one reads them until after they install, if ever? In my case, the installation Help files are also publicly available online, so you can, if you were so inclined, read the installation instructions online before you install the product. (HINT: Put an “install.txt” file with the installer download!) If you pay extra for technical support, I’m sure the company will hold your hand while you install their product and help you avoid any bumps in the road.

There is so much repetition in this help file, it’s ridiculous!
OK, Grandma, calm down. This is called a “help file,” and the reader can jump into the story at any part in the story. In fact, it’s not a story at all. There is no beginning, middle, or end. It’s a collection of “how to” topics, not a novel. So when Mr. Admin is trying to create a user and starts banging his head against his desk because he can’t figure it out on his own, he can click “Help,” search for “how do I create a user?” and then read a topic called “Creating a User.” He doesn’t want to know why to create a user. He doesn’t want to know what happens at the application level when the user is created. He doesn’t want to know where in the database the user is stored. Right now, all he wants to know is, “how do I create the doggone user?”

(And while you’re laughing because I formatted a sentence in the help with red, bold text, know that I did that because when it was regular, black text, no one would read it. They would scan right past it. I have yet to make it blink, however.)

Why You Need a Technical Writer

Why do I need to hire a technical writer?
My intern did a fine job on that manual last year.
Sure there were a few spelling and grammar errors,
but Word caught most of them.
We don’t have time to create online help,
but, hey, no one reads it anyway!
That’s why we have a help desk!

Having an on-staff technical writer, whose only job is to create properly written, prepared, and presented documents, shows customers that you endeavor to provide a quality product and encourages repeat business.

As technology inserts itself into every aspect of daily life, there is an increasing need for clear, concise, accurate documents to explain that technology. To minimize training and customer-support overhead, savvy business managers provide professionally produced user guides and tutorials. If developers, engineers, or other high-level staff are writing your user guides, not only are you getting a sub par, hastily prepared document, but you are taking time away from your staff’s development, engineering, or other important tasks. Providing incomplete, inaccurate, confusing documents puts a negative face on your organization and encourages potential customers to take their business elsewhere.

Unfortunately, many companies provide user guides simply as an afterthought or to fulfill a customer requirement.

“Manuals” are frequently written by engineers who don’t want to “waste” their time writing help files–often with English as their second language. Many companies will ask managers or assistants to produce end-user documentation, resulting in documents that are hardly worth the paper they are printed on–or the salaries expended in their production.

A skilled technical writer researches the document’s target audience, determines the information required, and delivers it in a format that fits the need.

Engineers or developers might be experts in their fields, but advanced writing skills are not normally a part of their college curriculum. Technical people typically write to impress other technical people, rather than to get their point across in the most clear, concise manner possible. Also, a salesman’s or manager’s silver tongue in the boardroom doesn’t necessarily translate well into writing. On paper they can seem pompous and lacking in necessary information.

Technical writers design, write, edit, and manage a variety of documents.

  • “How-to” guides
  • Training guides
  • Policies and procedures guides
  • Newsletters
  • Reference books
  • Company newsletters
  • Annual reports
  • Business reports
  • Software user guides
  • Hardware user guides
  • Installation guides
  • Online help
  • Online tutorials
  • Computer-Based Training (CBT)
  • Operating instructions
  • Web site content
  • Promotional mailings
  • Brochures
  • Slide presentations
  • Standardized forms
  • Articles for newspapers, magazines, journals
  • Questionnaires/surveys
  • Templates
  • White Papers

Expertly prepared and managed documents improve every aspect of your business:

  • Current customers become repeat customers when accurate and easy-to-use guides are provided with your product.
  • Well-written and informative catalogs, corporate reports, and marketing materials attract clients and investors.
  • Clear, comprehensive training and procedures documents make employees more efficient.
  • Accurate and clearly written policy manuals avoid legal hassles with employees.
  • A well-written and organized Website presents a professional image to potential customers.