Sunday, January 31, 2010

HELP FOR HAITI

AFTER EARTHQUAKE




BEFORE EARTHQUAKE







JOIN OUR HANDS , EVERY ONE THINKS HAITIANS


Friday, January 29, 2010

Preventing injuries during surgery due to technical mistakes [Respectful Insolence]





















You’ve probably heard the oft-repeated charge of “alternative” medicine advocates. If you get into a debate or conversation with one, you can almost count on seeing or hearing it before too long. Indeed, we heard a variant of this very claim yesterday coming from über-woomeister supreme Deepak Chopra. I’m referring, of course, to the rant against “conventional” medicine that medication errors claim 100,000 lives a year. Of course, as Mark pointed out, “conventional” therapies actually work, and because they work there’s risk to them. Moreover, its hospitals actually care for seriously ill patients. However, even so, medical errors are more prevalent than they should be, and this is where the difference between “conventional” and alternative medicine is most apparent. No, not because conventional medicine produces errors. What I’m referring to is how, unlike “alternative” medicine, conventional medicine is engaged in a concerted effort to minimize medical errors, be they systemic or by individual physicians.
As hard as it may be for some to believe, in many cases surgeons are spearheading such efforts, doing studies that seek to identify causes of bad outcomes and surgical errors. Not long ago, I discussed one such study, which looked at morbidity and mortality rates by the month in teaching hospitals and seemed to indicate that morbidity and mortality increased in July and August, paralleling the arrival of new interns, residents, and fellows every year. The studies had some flaws, but the effort was admirable. Now, hot off the presses in this month’s Annals of Surgery is study that seeks to characterize patterns in surgical errors. It’s coauthored by Dr. Atul A Gawande, the Harvard surgeon who’s made a name for himself with his books Complications: A Surgeon’s Notes on an Imperfect Science and Better: A Surgeon’s Notes on Performance, both of which deal with complications of surgery and how to improve medical care.
The study, Patterns of Technical Error Among Surgical Malpractice Claims: An Analysis of Strategies to Prevent Injury to Surgical Patients, took a rather clever strategy. As much as we physicians hate it, malpractice suits represent a source of data that is seldom used but can often identify glaring medical errors that can’t be ascribed, even obliquely, to differences in surgical opinion. We’re talking about wrong-side surgery errors and the like. Of course, while I find the information in this data as interesting and potentially useful as Dr. Gawande did, I would be remiss if I didn’t point out that the threat of malpractice suits can also distort medical care, leading doctors to practice “defensive” medicine, actually increasing the risk of mistakes by subjecting the patient to more tests and procedures. Be that as it may, actual malpractice suit data do provide a unique insight into surgical errors.
Such an insight is needed because, as the article points out right in the first paragraph, between one-half and two-thirds of hospital adverse events are attributable to surgery and surgical care. Also, the sorts of errors that occur in surgical care tend to be different than those that occur on medical services, making many of the studies of medication errors in hospitals not easily generalizable to surgical care. The big difference is that most surgical errors occur in the operating room and most are “technical” in nature. Technical errors are errors in which some aspect of the surgery is not done properly, and can include errors of manual skill and errors of “surgical judgment” (i.e., decision-making in the operating room) or knowledge. An example of a purely technical error includes accidentally cutting something that shouldn’t be cut, whether due to carelessness or failure to identify the anatomy properly, or a tie on a blood vessel that’s improperly tied, leading it to fall off later. These errors, if recognized promptly at the time of surgery, often cause little or no morbidity because the surgeon can fix the problem right away, such as when surgeon makes an accidental knick in the bowel, sees the hole, and sews it up right away. If unrecognized, however, such technical complications can lead to devastating complications, the hole in the bowel being a classic example, which may not be recognized if small. The patient will slowly leak stool into the abdomen and become really septic within a few days of surgery.
Another class of surgical error is the error in knowledge or judgment. Surgery is unique among medical specialties in that, while doing operations surgeons are constantly making decisions in real time and acting on them. There’s not much time to contemplate, because you can’t leave the patient under anaesthesia while you walk off to the library to look up literature on what you should do. This aspect of surgery is often what is tested on board examinations, where the candidate will be asked what he or she would do, for instance, if a certain unexpected finding were to be encountered at the time of surgery. One classic example of a “judgment” question is what to do if you find an ovarian mass in a woman undergoing a splenectomy for a hematological disease. Another is what to do if an abdominal aortic aneurysm is found at the time of surgery for a malignant polyp. (These days, if a patient has a decent-sized colon cancer, he would be likely to have had a preoperative CT scan, which would identify the aneurysm making this question a little less relevant than it was, say 20 years ago.) Errors in knowledge tend to involve doing the wrong procedure for a condition, a classic example being performing a simple cholecystectomy for an invasive gallbladder cancer.
These sorts of errors can occur at any phase of surgical care, and numerous studies have been done to try to identify causes. Such errors and adverse outcomes have been attributed to low hospital volume, breakdowns in communication, systems shortcomings, fatigue, lack of experience in trainees, and many other causes. These studies have led to many proposals of how to minimize such errors, many of which are controversial, such as referral of certain kinds of cases only to high volume centers.
In order to characterize surgical errors that led to serious injury to patients, this study examined a database of closed malpractice claims. 444 such claims were examined in which 258 were identified in which an error resulted in an injury. Examining the claims, reviewers identified 135 (52%) in which it was judged that a technical error was a major contributing factor to patient injury. Error was defined according to the Institute of Medicine definition: “the failure of a planned action to be completed as intended (i.e., error of execution) or the use of a wrong plan to achieve an aim (error in planning).” Technical errors were those where reviewers believed that an error of operative technique directly contributed to the adverse outcome, either because of manual error (error of execution causing injury to viscera or vasculature, for example) or judgment or knowledge error (wrong timing, wrong selection of procedure, failure to diagnose complications, wrong site surgery).
There were 140 technical errors identified. Attending surgeons were responsible for 69% while 27% involved both the attending and trainee. Reassuringly, only 4% were due to actions by surgical residents or fellows alone. Less reassuringly, most of the technical errors caused serious injuries, with 49% resulting in permanent disability and 16% resulting in death. Not too surprisingly, given that these were severe errors, the kinds that lead to malpractice suits, 31% involved gastrointestinal surgery, 15% spine surgery, 12% gynecologic surgery, and 9% non-spine orthopedic surgery. In terms of error type, 91% of technical errors involved manual error and 35% involved judgment or knowledge errors. A summary of the types of manual versus judgment/ knowledge errors is summarized in this table:
Perhaps the most interesting findings were the contributing factors to technical errors. Not surprisingly, 69% of technical errors involved complicating factors, with 61% having patient-related factors (difficult or unusual anatomy 25%; reoperation 20%; urgent or emergency operations 17%). There were also a number (16%) of equipment use misadventures. Not surprisingly, experienced surgeons were less likely to have equipment use misadventures than inexperienced surgeons and more likely to make errors related to reoperative surgery. The reason this is not surprising is that the anatomy is often hard to ascertain in reoperative surgery due to scarring and adhesions, and more experienced surgeons are more likely to attract referrals of more difficult patients. What one might find surprising on the surface is this comment in the discussion:
Almost three-fourths of technical errors in this study involved fully trained and experienced surgeons operating within their area of expertise and 84% occurred in routine operations, for which advanced expertise beyond a standard training program is not required or expected.
What this tells us is that it is during the common operations when errors happen most frequently. As an accompanying editorial puts it, “It is not the neophyte doing the 10-hour Whipple that leads to most malpractice claims; it is the experienced general surgeon doing a gastrectomy on a patient with three previous upper abdominal operations and a replaced left hepatic artery.” This should not be that surprising, given that highly complex operations tend to be performed in academic medical centers by highly specialized surgeons and surgical teams. What this study also suggests is that the best strategy to have a rapid impact to reduce surgical error may be to develop strategies to improve decision-making, operative planning, and team performance for common, not necessarily the highly complex, operations. Moreover, it suggests that volume- or experience-based limitations on privileging for high-complexity operations would only have an impact on a relatively small minority of surgical errors. In other words, a bigger bang for the buck in this respect would likely result from focusing on interventions to improve performance and decision-making in routine operations in emergencies and on high risk patients.
Another interesting aspect of this study was raised in the editorial, namely the question of how often experience itself invites disaster:
How often did experience itself invite disaster? I am thinking of a case of my own recently where I embarked on a difficult liver resection in an 82-year-old man who had undergone 8 cycles of chemotherapy. The lesion was in an awkward place and I knew of the increased risk. Yet, my experience made me confident that I could “get away with” a procedure that I would flunk a young surgeon for if she proposed it during a board examination. This reminds me of the comment made by the first officer of an airliner that ran off the runway in Burbank, California, after an unstabilized, too fast, nighttime approach. “I’d seen it work out before,” he said.
This is a telling observation. Pretty much every surgeon knows of a “cowboy” who loves taking on the most difficult, highest risk cases, sometimes even to the point of going too far and operating on patients who probably should not be operated on. They may be so good that they do “get away with it” most of the time, but it’s still riskier than it should be.
I think the takehome message from this study is, as for many things in surgery, that simple interventions in common problems are likely to yield the most benefit. Big cases like Whipples and liver resections are often examined at a frequency that far outstrips their actual frequency relative to common operations like hernia repairs and cholecystectomies. After all, the median number of Whipple operations done by a typical private practice general surgeon per year is zero, while the same surgeons may do a couple hundred or more laparoscopic cholecystectomies during that same time It would almost certainly pay off more dramatically to take care of fixing factors leading to errors in the common “bread and butter” operations first.
http://medicalnewsweek.com

Monday, January 25, 2010

Three Easy Mistakes to Avoid When Doing Keyword Research

In the process of creating targeted keyword lists for any particular project it's easy to simply say "target the keywords with the highest search volume". This is almost never true, of course. Clients often want the moon delivered on a platter but that doesn't mean that's what they actually need. The following tips are a few of the tricks I've learned as I cull a keyword list.

Using Plural when Singular is an Option

This goes hand in hand with realizing what the intentions of your audience are. If your potential customers are searching for a birthday present for their mother, they are not going to look for "PS3 controllers" when "PS3 controller" will do. They're only looking for one.
There's nothing wrong with talking about the product in the plural on the page. That should be all the targeting you need for those terms.
Side note: your customers are going to be in trouble for giving a PS3 controller to their mothers.

Targeting Local Keywords when You're not Local

Larger companies often target a global market. When locality comes into play, I usually recommend that a client take full advantage ofGoogle Local, Yahoo Local and Yelp.
If you have an international market, then trying to be in every local search becomes painful. Target the global terms if you're a global company and let the utilities mentioned above do the work for you to get in the local markets.

Targeting Misspellings

Actively trying to target a misspelling is terrible waste of time. The SERPs are going to realize the mistake and send your customers to the correct spelling anyway, negating any work you may have done.
The current suggested course of action is to include the misspellings in the meta keywords. While it's already known that Google does not use the keywords tag for any of their weighting algorithm, it is suspected that the keywords are used for relevancy — a perfect place for misspellings.
Side note: "misspellings" is very easy to misspell.

http://www.bloggapedia.com/blog_post.php?p=Three-Easy-Mistakes-to-Avoid-When-Doing-Keyword-Research-1733594

Friday, January 22, 2010

sexual mistakes made by women

Men and women are equally guilty of mistakes when it comes to sex. In addition to money issues, sexual dissatisfaction is among the top reasons why relationships fade. Busy lives, careers, stress and children are other factors that contribute to the sexual downturn of couples. However, it is often one person who is particularly dissatisfied with their sex life because their partner is not as sexually charged as he or she would like them to be.
At the risk of ruffling some feathers, I felt it was time to do a follow up article to “Top 10 sexual mistakes made by men”. However, this time we focus on the most common sexual blunders and faux pas made by women. Remember that it takes two to tango. Communication, trust and sexual variety between partners are always the best ways to avert animosities in the bedroom.
The following is a Top 10 list of things for women to avoid when it comes to sex:
1) Lack of sexual communication: As stated previously in “Women, Please! Just Tell Us What You Want!” Men are not mind readers. We want to satisfy you but all women are different when it comes to the right recipe for ecstasy. It is important for a woman (just as it is for a man) to share their sexual fantasies and desires. Do not be afraid to talk about sex with your partner. Tell your man how to better satisfy you or if there is something new you would like to try. When he gets it right, reward him with moans of pleasure or a naughty grin. In addition, many men find it a turn on when a woman uses a little dirty talk in the bedroom too.
2) Failure to show your sexual energy: Sure, most females were brought up to be “good girls” but when it comes to sex, hang that halo on the bedpost and let him know what a bad girl you can be. Many men view a woman’s lack of sexual drive and energy as her not wanting or enjoying sex. If you enjoy the intimacy you share then show him. Initiate sex more often, moan, thrust and be more assertive when it comes to sex. Most men enjoy it when a woman takes charge on occasion. Push him down on the bed, climb on top and show him what a tigress you can be.
3) Don’t expect him to think like a woman: Sure, most women equate romance with sex. Unlike a woman, men do not always need romance to have sex. In fact, sometimes your man may simply want the physical pleasure of sex without dinner and a movie or an hour of foreplay and heavy petting on the couch. This is not to say that your man is excused from being romantic on occasion, but do not make him “work for it” each and every time. Men enjoy sex and they do not need to be seduced to participate (but we do like that at times too).
4) Failure to experiment or add sexual variety: Simply put, don’t be afraid to try new things. Like food, you do not know if you will like or dislike something until you try. Women can greatly enhance sexual pleasure and reduce boredom in the bedroom by being more adventurous when it comes to sex. I suggest reading “Naughty Ways to Spice Up Your Love Life and Marriage” for some great suggestions to add more variety to your sex life. Go parking or try having sex outdoors. You might try some new adult toys or positions as well. Remember that “Variety is the spice of life and life is what you make of it”.
5) Expecting him to be responsible for your orgasm: This is a belief that can lead to disappointment all around. It is true that there is no greater reward from sex for a male than to bring his partner to climax but sometimes he cannot do it alone. The fact is that, as individuals, we are all responsible for our own orgasm. As a woman, you should not be afraid to touch yourself or use adult sex toys during sex. You can assist by showing him the right way to touch you or telling him “don’t stop!” Even if he finishes before you, that doesn’t mean that you have to stop. Encourage him to help you get there too. Lastly, it is always best to focus on providing pleasure to one another and enjoying the moment rather than thinking about the finale.
6) Using sex as a weapon: This is among the worst things that a woman can do to damage their sexual relationship with their partner. To withhold sex because you did not get your way is cruel and can only hurt your relationship in the long term. Never tell your man that you will deny him sexual pleasure as a means to get what you want!
7) Not having “make up sex” after a spat: Make up sex is some of the best sex a couple can have because it helps the two of you to reconnect and moves both partners past the argument. Sure, many couples have make up sex but even more couples do not. Of those that do, most report their greatest level of passion when they make up by making love. This goes along the same lines as you should never go to bed angry with one another. Besides, it’s always better to make love not war!
8) Being too critical of him: Let’s face it; men communicate more directly than women. Women who often criticize their man are often lacking the ability to communicate directly to convey their thoughts and feelings. This sometimes causes women to lash out and say things that can be hurtful. Men who are routinely criticized by their partner will often withdraw from being romantic and, in turn, their desire for intimacy is reduced. Instead of being overly critical of his shortcomings or mistakes, try talking with him to share your thoughts without throwing verbal daggers.
9) Being TOO gentle with his manhood: This is a common mistake made by many women. When it comes to a man’s penis, do not treat it too gingerly. Fact is that most men prefer a firmer touch than women do. If you have ever had the pleasure of watching him masturbate you will quickly see that he is anything but gentle with his penis. Here again, communication can be very helpful if you are unsure how to handle his penis. Ask him if you are doing things right or have him suggest ways to make it feel better when you touch him. Helpful hint: Use a water based lubricant like K-Y when stroking him lovingly.
10) Not going down: For some couples, oral sex is taboo and not a part of their sexual intimacy. But if your man wants you to fellate him and you are unwilling to do so then it can easily cause aggravation in the bedroom. This is something that you both need to talk about. Tell him how you feel about it but listen to him as well. If you simply cannot make yourself have oral sex with him then suggest other things you can do. If oral sex is not an issue for you, then again, ask him if you are doing it right. Fact is that nearly every man has faced the “wood chipper” at least once in his life. Word of advice: Gently running your teeth over the head can feel good but beyond that…no teeth!

http://www.examiner.com/x-3357-Indianapolis-Marriage-and-Sex-Examiner~y2009m6d11-Top-10-sexual-mistakes-made-by-women

Saturday, January 16, 2010

Are You Making These Writing Mistakes?

Inexperienced technical writers typically make a number of avoidable mistakes, including parroting the SME and hard-coding cross-references (x-refs). Here is a description of the mistakes to avoid.
Not Understanding the Product or Application
This problem takes two forms: In the first, the subject-matter experts (SMEs) write the preliminary documentation, and then the writer does nothing but edit it (this is the worst kind of writer and I am assuming that, if you are reading this, you are not one of them). In the second, the writer does all the writing, but repeats verbatim the words of the SME in the document
. Technical writers know they've done this when they write sentences that they don't fully understand.
When you review your document, try to read it from the user's point of view. Imagine that you are reading it for the first time. If your document contains any sentences that you don't understand, assume that your reader won't understand them either. Rewrite them.
Parroting the Subject-Matter Expert (SME)
All professions and companies have a vocabulary that is meaningful only to those in the company or the profession. A common mistake among both SMEs and writers is to assume that the user understands the vocabulary.

To illustrate, I once shared an office with a software developer who was in charge of seeing that the separate parts of the application worked together. Every so often, someone would come in to report that a particular software function had abended. When I asked these people what abended meant, they were at such a complete loss for words it was as though I had asked them to define the word and. I could see thatabend held so much meaning for them that they were unable to condense all of its concepts into a single definition.
A short time later, I reviewed a document that contained the word abend. I called in the writer and asked him what it meant. He looked me in the eye and said, "I don't know," thus providing me with a golden opportunity to give my "Don't parrot the SME speech," which is:
As technical writers, it is our job to translate the complex and puzzling into something that everyone and anyone canunderstand. You and I represent Joe User. If you don'tunderstand something, it is a sure bet that Joe User won'tunderstand it either. Never repeat verbatim the words of the SME. Always ask for clarification.
Now I know it is embarrassing to stand in front of the SME asking questions that the SME clearly regards as stupid, but sometimes it's the only way to get information. You have to persist. And if you can't get the information from the SME, then you have to do other kinds of research. Check the Internet, go the library, read the standards. Do whatever it takes to ensure that each word, sentence, and paragraph in your document is meaningful to everyone.
Notice that my "Don't parrot the SME speech" also contains a concise definition of technical writing:
Technical writers translate the complex and puzzling into something that everyone and anyone can understand.
Finally, to find out what abend means, click here. Or, if you have installed the Google toolbar in your browser, type define: abend in the Google search box.
Working Without a Plan
When you work
without a plan, you create extra work for yourself or for someone else later on. Without a plan, you will find that new information cannot easily be incorporated into your documents as the project progresses or when the software is revised. In fact, without a plan, you will run into a host of problems.Your plan should include:
  • a list of the documents or chapters that will be written, usually:
    • product description
    • installation guide
    • configuration guide
    • user guide (or system administration guide)
    • others
  • the file-naming conventions that will be used
  • the location in the network where the documents will be stored
  • the method by which the documentation will be delivered to the customer, e.g.:
    • shipped (hard copy)
    • shipped (CD)
    • downloaded from a server
    • integrated with the application
  • the method by which the customer will access the documentation, e.g.:
    • from a binder
    • from a web page or CD
    • through a help button in a GUI
As you begin to understand the product or application you are documenting, you must also plan the documents themselves:
  • the look and feel of each document in relation to itself and to the other documents in the suite
  • the content that will be the same in each document (boilerplate)
  • the content of each document and chapter
  • the order in which the information is to be presented
No File-Naming Convention
Creating a file-naming convention is one of the most considerate things you can do for the other
technical writers on your team and for thetechnical writers who will replace you after you have moved onto other projects.

Imagine that you are documenting a network application called QDO. This network has four nodes (named BBB, QETO, IB, and PBN), each of which requires a product description, installation guide, configuration guide, and user guide. IB and QETO also require a command reference guide, and since PBN includes a GUI, it requires online help for 25 features, each of which comprise the functions of Add, Modify, and Delete. Confused? Unless you have a file-naming convention, everyone else at work will be too.
Your file-naming convention should make sense to you and to others. For example, you might decide on a file-naming convention that starts with the node name followed by the document name. Thus the file name for the product description of the BBB node would be bbb_pd.doc (or bbb_pd.fm), and the filename for the installation guide of the IB node would be ib_inst.doc (or ib_inst.fm). It is probably not necessary to put the application name in the file name because all documents associated with the application will be kept in a folder named after the application. If you are creating a large document from a number of smaller documents, consider using a file-naming convention for the smaller documents too.
One caution: do not use "chapter 1" (e.g., bbb_pd_chapter1.fm), etc., in your file-naming convention, because chapter order tends to shift during the project, and because new chapters will likely be added throughout the life of the product. Instead, use a word that indicates the content of the chapter, otherwise your file names might end up looking like this:
bbb_pd_cover.fm
bbb_pd_title.fm
bbb_pd_toc.fm
bbb_pd_intro.fm
bbb_pd_
ch2.fm
bbb_pd_
ch1.fm
bbb_pd_
ch3.fm
bbb_pd_gloss.fm
bbb_pd_back.fm
No Document-Numbering Plan
Most companies do in fact number their documents, but the number, such as CQZ3391-Y, is often meaningless. Since one of the purposes of a numbering plan is to make it easy for the ordering center to assemble a product and ship it to the customer, you should create a numbering plan that makes sense. A more intuitive numbering plan, therefore, is xxx-yyy-zzz, where:

xxx is the application name
yyy is the node name
zzz is the product (
hardware
, software, or document) name
Thus, continuing with our network application example above, let's say that the QDO application is given the number of 654, the BBB node is given the number 175, and the IB node is given the number 176. All BBB products associated with the QDO application will be numbered 654-175-zzz (I'll get to the zzz in a moment) and all IB products will be numbered 654-176-zzz.
Now let's say that, for every node your company produces, you will create one or more of the following documents:
  • product description
  • site preparation guide
  • acceptance testing procedures
  • installation guide
  • configuration guide
  • user guide
  • command reference guide
  • alarms and notifications guide
  • troubleshooting guide
  • maintenance procedures
You can specify that each one of these documents will have a specific number. All of your company's product descriptions might be numbered, say, 801, and all site preparation guides 802. Number the remaining documents consecutively. With this numbering plan, the productdescription for the BBB node will be numbered 654-175-801, the productdescription for the IB node will be numbered 654-176-801, and the maintenance procedures will be numbered 654-yyy-810.
The document number should be displayed in your document. In my documents, I put the document number on the title page and in the footers.
No Revision-Numbering Plan
The revision number indicates which version of the document the customer is using, and which version you are writing. It is a good idea to have two sections to your revision number. The first part indicates the version of the application, and the second part indicates the revision number of the document. Thus:

  • Version 1.0 is the original version of the document for the first version of the product or application
  • Version 1.1 is the first revision
  • Version 1.8 is the eighth revision
  • Version 2.0 is a completely new release of the document for the second version of the product or application
The revision number should be displayed in your document. In my documents, I put the revision number on the title page and in the footers.
Not Using a Template
Of the many companies I have worked for over the years, nine of them were large enough and old enough to have fully developed templates, but only two of them did. Considering how much time (which, in business, is money) is saved by the use of templates, I am amazed that more companies don't use them.

Many people think that a template defines only the paragraph styles used in a document. In fact, a well-designed template contains not only paragraph styles, but also the layout for every page element (headers, footers, headings, tables, paragraphs, steps, notes, precautionary messages, etc.) and every book element (front cover, title page, TOC, chapters, glossary, back cover, etc.). All of these elements require a great deal of thought and quite a lot of time to design so that the template is easy for the writer to use and easy for the user to read.
If you design your documents from scratch for every project, they are likely to be poorly designed. Furthermore, the time you spend designing the templates must be added to the cost of each project, as well as the extra writing time demanded by a poorly designed document.
Templates create focus and reduce the amount of work. If you are documenting an application's alarm-clearing procedures, for example, you will find the job much easier if you are working with an alarm-clearing-procedures template. By pre-designing a document from cover to cover, and by including boilerplate text wherever possible, you allow writers to focus on the content of the document and not on its design.
Templates reduce errors. For example, the title of a book generally appears in several places throughout the document, such as on the front cover, on the title page, in the footers, and on the back cover. The problem is that book titles have a tendency to change several times during a project. Technical writers usually remember to change the title on the cover page, but often forget to change the title page, footers, and back cover. Templates allow you to link these elements so that if one element changes, all of the related elements change automatically.
Templates are reusable. Once you have created the first set of templates, you never have to create them again. You can reuse them in every project after that.
Templates establish your company's corporate brand in the marketplace. When documents are created from scratch for each project, every document you send to your customers will have a different look and feel. Why not create a template that allows customers to recognize your excellent documentation?
Templates help your customers feel comfortable. Unlike marketing documents, which are intended to impress your customers with your way-ahead-of-the-competition style, technical documents should reassure your customers with their predictability, comfort, and ease of use. Templates create a consistent style, which helps your customers know what they will find in your documents.
Using a One-Size-Fits-All Template
Of the companies that do create templates, many create a single template that is intended to be used for all documents, whether the document is a product description, for example, or a command reference guide. Such a template can become a constant source of irritation because it never quite suits its purpose. There are always more paragraph styles than are required in any one document and these must continually be tweaked to meet the purpose of the document. For example, a command reference guide needs styles for commands, command responses, and parameters, but a product description does not. Similarly, procedural documents such as installation guides require styles for numbered steps, but a product description does not. Furthermore, some documents—command reference guides, for instance—often require narrower margins than the other documents in the suite.

Rather than creating a single, multi-purpose template, create a template for each type of document. While the look and feel of all the documents should appear to be the same from the user's point of view, subtle differences in the design of the templates will make the documents easier to write.
Using a Bells-and-Whistles Template
Many companies do not have the skills in house to design their own templates and so they outsource the job to another company. The first mistake many of these outsourced companies make is to design a single template, as described above. The second mistake they make is to add so many unnecessary features to the template that it is impossible to use.

I once worked for a telecommunications corporation that, despite its longevity and size, was only just beginning to develop its policies and procedures for document creation. At one point, the company sent out a template to the writers, saying that we were required to use it from now on. It had all sorts of fancy features like grid marks, crop marks, tables to be used in this kind of document, tables to be used in that, headings for this and headings for that, all kinds of automatic document-management features (none of which worked), and much, much more. Unfortunately, none of us could figure out how to use it, and so we didn't.
It must have cost a small fortune to create such a feature-rich template, particularly since the work was not done in house, but outsourced to another company. I am told that the template is still not in use. What a waste of money!
A template should not only ensure that the documentation has the same look and feel, but it should also make the task of writing easier. The greater the number of fancy design features in a template, the more difficult it is for the writer to use. And since fancy design features do not benefit the customer by making the documentation easier to read, they are completely unnecessary.
You should design a template for each type of document your company creates. Each template should be designed so that it is easy to use. If this is the first time you have created templates, expect to spend about one month designing the first template and a week or two on the others. Expect to spend more time if you also plan to add boilerplate text to your templates. You will probably find that you have to tweak the templates frequently as you write the first version of the documentation. For example, if the standard text area in your templates is 6.5 inches, you might discover that commands are too long to fit. In this situation, you might decide that documents containing commands should have a text area of 7.5 inches.
For help in designing your templates, one of the first things you can do is open any reference book and examine how the publisher has designed it. Notice the position of the book elements and the page elements, then try to recreate them in your templates. I also recommend that you get a copy of The Chicago Manual of Style. You will refer to it often.
Once you are an experienced template designer, you will find that you can create a whole suite of templates in less than a month. If you are a consultant, template design is an excellent skill to have and one that you will use frequently!
Hard-Coding the Table of Contents, Cross-References, and Caption Numbers
This error is the hallmark of the inexperienced writer. If you hard-code the table of contents (TOC), cross-references (x-refs), and caption numbers (i.e. you type them by hand rather than letting your desktop publishing software create them), they will be out of date, if not by the time your document is released, then as soon as it is updated by someone else. If you don't know how to create these things electronically, consult the help files of your desktop publishing software.

Multiple Tab Stops
This problem does not affect the user, but it irritates anyone who has to update your documents. This problem is often seen in longer system responses, such as
tabstops

Inexperienced writers tend to use the desktop publishing software's default tab stops to align the columns in system responses, which can result in multiple tab stops between the text elements. But let's say that, in the next version of the software, another column of information is added in the middle of the system response. The writer will have to add, delete, or re-set all of the tab stops in order to realign the columns.

Always delete extra tab stops so that there is only one between each text element.
No Glossary
Many companies regard glossaries as nice to have rather than essential. But try to imagine reading your document for the first time. All those acronyms and technical terms increase the reading difficulty of your document a thousandfold. Actually, maybe it's only a hundredfold. Regardless, out of compassion for your bewildered and busy reader, include a glossary with your document.

To go to my page about creating glossaries, click here.
Putting Information in the Wrong Order
In step-action procedures, many writers first tell the user what to do, and then they tell them where to do it. In fact, you should first tell the user where to do the task, and then tell them what to do. This is called "situating the user."

Example
Incorrect: Select Style from the Format menu.
Correct: On the Format menu, select Style.
In non-procedural documents, start with the big picture and then narrow in on the details. For example, in the product description for the BBB, you would start by describing the QDO. You would then describe the BBB node's relationship with QDO and its relationship with the other nodes in the network. Each chapter begins with a short summary of the contents of the chapter, as illustrated in the following "quotation" from the first chapter of the non-existent QDO BBB Node Product Description:
The BBB node manages communication among the four nodes of the QDO network. The four nodes are:
· BBB
· QETO
· IB
· PBN
This chapter describes the QDO network and provides an overview of the functions of the four nodes.
Poor Spelling
When you consider that the spell-check function has been around since the beginning of desktop publishing history, it is amazing that more people don't use it. I know I can't spell, and since the user guide for a popular help-authoring tool contains several spelling errors, I know that other writers can't either. There is no excuse for releasing documents that contain spelling errors. Do a spell-check!

Future Tense
Inexperienced writers often describe an application's response to the user's input as though it happens in the future. For example, they might write, "When you press
Enter, a warning message will appear." In technical documentation, nothing happens in the future! The future tense causes the reader to worry. When will the message appear? What if it doesn't appear?

Always write in the present tense:"When you press Enter, a warning message appears."
Perhaps you are saying to yourself, "Well that would be fine if our warning messages took less than ten seconds to appear on the screen. That definitely requires the future tense!" Wrong. In such a situation, you would write, "When you press Enter, a warning message appears on the screen after ten seconds have elapsed." Better yet, write this as a step-action procedure:
  1. Press Enter. After ten seconds, a warning message appears.
Conditional Tense
I wouldn't be talking about this problem if I'd never seen it, but it is quite rare. The use of the conditional tense can occur in documents that are written before the application is complete—when the development team is not entirely sure how the application will respond to the user's input. For example, the SME might tell you, "When the user presses the
ENTER key, a warning message should appear on the screen." Unless you hear otherwise, always assume that the warning message does in fact appear. Of course, you should occasionally ask the SME to confirm that the application responds as described.
Contractions
Contractions are acceptable in many documents, including letters and web sites. Contractions help you to appear friendly and approachable. But the readers of a technical document will never regard you as friendly and approachable, no matter what you do. In fact, a friendly and approachable style in a technical document could make your readers feel patronized. Always use a formal style in technical documents.

Non-Parallel Structure In Bulleted Lists
Begin each item in a bulleted list with a word of the same grammatical type. If the first item in a list begins with a verb, for example, then all the items in the list must begin with a verb.

Uncertain Punctuation In Bulleted Lists
Do not use a period after items in a bulleted list unless they are complete sentences. But, if the list contains a mixture of clauses and complete sentences, put a period at the end of each list item.

Do not use the style wherein each list item ends with a semicolon, the penultimate item ends with a semicolon followed by the word and, and the final entry ends with a period.
Unclear Antecedent ("This")
Do not begin a sentence with the word
This unless its antecedent is obvious.

Example
Incorrect: Put on the wrist strap that is attached to the equipment shelf. This prevents static from damaging the circuit board. Correct: Put on the wrist strap that is attached to the equipment shelf. The wrist strap prevents static from damaging the circuit board.
Chapter Number Precedes Page Number
Do not use the page-numbering style wherein the chapter number precedes the page number. This style makes it hard for users to find a particular page. This page-numbering style made sense when only hard-copy documents were delivered to the customer because it allowed companies to release updates without having to reprint the whole document. Nowadays, however, the cost of sending hard-copy documentation to the customer is prohibitive and most companies therefore prefer to deliver their documentation electronically. Unless your company sends out hard-copy documentation, use consecutive page numbers.

And/Or
Do not use
and/or in your sentences. It delays your readers by forcing them to parse the sentence in order to understand it. Instead, use . . . or . . . or both.

Example
Incorrect: Would you like sugar and/or milk with your coffee? Correct: Would you like sugar or milk with your coffee, or both?
Jargon
All companies and all professions have their own vocabularies that should not be used in your documentation.

Examples
Incorrect: Abort the procedure. Correct: Close the procedure.
Incorrect: Energize the VCR Correct: Press the Power button on the VCR.
Incorrect: Kill the connection. Correct: Close the connection.
Widowed Headings
All headings must be followed by text. Never place one heading directly after another without intervening text.

Incorrect Position of Warning Messages (Danger, Warning, Caution)
Any step that could cause injury, damage, or a loss of service or signal if performed carelessly or incorrectly must be preceded by a warning message. Do not place the warning after the step.

Use Danger messages to prevent death or injury, Warning messages to prevent damage to equipment, and Caution messages to prevent a loss or degradation of signal or service.
Note: Standards for precautionary messages are available and these standards have different instructions from the ones I have provided above. ANSI Z535.6-2006, Product Safety Information in Product Manuals, Instructions and Other Collateral Materials, is the American standard. ISO 3864-2:2004, Graphical symbols -- Safety colours and safety signs -- Part 2: Design principles for product safety labels, is the international standard. The American standard requires the use of both graphics and text; the international standard requires the use of graphics only. Use a standard if your company requires it.
The warning message must indicate the consequences of a misstep.
Example
Incorrect: Danger! Ensure that the unit is grounded before switching it on. Correct: Danger! Risk of electrocution. Ensure that the unit is grounded before switching it on.
Neglecting to Think of Your Internal Customers
External customers are the people who read your documentation. Internal customers are the people you work with every day, the people who translate your documentation into other languages, and the people who will replace you after you have been promoted to CEO.

As you write your documentation, set up your file structure so that other employees can understand it. Avoid cryptic file names and do not bury your folders deep within the network or save them on your personal drive.
Do not hard-code tables of contents, cross-references, or caption numbers. Do not use multiple tab stops between text elements.
Consider the difficulties of translation as you write. Write so that every word and sentence is perfectly clear and unambiguous. Avoid jargon: words such as abort and kill do not mean end and close in other languages.
Be careful about words that have different meanings for different audiences. For example, the word table can mean different things for writers, chefs, software designers, and geographers.

LinkWithin

Related Posts with Thumbnails