You might have noticed the complete lack of social niceties like "please" in Informix documentation. Occasionally, I do get messages to review from developers that say things like "Please read the Guide to SQL: Syntax for information on the syntax." Or even better: "Please contact IBM Software Support." I have to take out the "please" because it is against IBM style guidelines.
The official IBM Style guideline on "please" instructs us not to use "please" in IBM technical information: Terms of politeness are superfluous, convey the wrong tone for technical material, and are not regarded the same way in all cultures.
In some cultures, when you use a word like "please," it indicates that the action mentioned is optional. We have to take into account that our documentation will be translated and also that it will be read in English by people whose first language is not English.
So you see, we are not being rude--just authoritative!
Appropriate Content: Informix Documentation Team
From archive: June 2010 X
WilliamBelisle 2700009EDR 1,619 Views
Although it seems archaic now, before digital cameras and photo printers exploded in popularity, people recorded their photographic images on light-sensitive film. When film was popular, I used to teach an introductory photography class at Boston University. Each week, students would receive an assignment that emphasized a basic photographic technique, such as depth of field or stopping motion with a high shutter speed. Students would shoot their own photographs, bring the film to the school darkroom, and develop and print their photographs.
Every Monday night, students would take their painstakingly hand-developed and printed 8 by 10 images and thumbtack them to corkboard that surrounded the classroom. The entire class went around the room and critiqued each person’s photos. In these sessions, technique was graded along with composition, subject matter, and so on. Because students often were marked lower because of fingerprints, scratches, or dust on their negatives, these sessions naturally became known as negative feedback sessions.
The instructions that follow show how to leave feedback about the Informix documentation – either negative or positive.
For best results, use Microsoft® Internet Explorer Version 6.x or Version 7.x or Mozilla Firefox Version 2.x or Version 3.0. Mozilla Firefox Version 3.5 or later might provide inconsistent behavior.
You can rate topics based on your level of satisfaction by clicking a star at the top of the topic pane. Ratings are based on a 5-star scale.
Comment on an entire topic or selected text within the topic
There are three kinds of comments:
* Comments on the topic in general
* Comments on an element of the topic (for example, a heading or sentence)
* Comments on a section of content that you select
To add a comment:
Reply to comments
To reply to an existing comment, click the Reply link under the comment in the comment pane, and add your response to the comment in the pop-up window.
Delete your comments
You can delete the comments that you added before authors or other reviewers reply to them. Click the Delete link below the comment.
Subscribe to pages or the entire site, to be notified of new comments
You can watch specific topics to get email notification of any comments to them. Click the Watch this Page link in the upper right corner of the topic pane.
To stop watching topics, use one of the following methods:
Click the RSS Subscribe link to receive updates in your RSS feed reader.
You can also get notification of major updates in the information center by subscribing to the information center RSS feed.
WilliamBelisle 2700009EDR 1,618 Views
A number of years ago when my kids were small (ages 6 and 9) I planned a full-day “boys-only” one-day adventure/trip to the Grand Canyon. After driving to our local airport, we boarded a small America West Bombardier Dash 8 twin-engine prop plane. Neither had ever been on a plane with propellers and I could see the excitement on their faces.
After a short bumpy flight, we landed at the Grand Canyon Airport near Tusayan at the entrance to the South Rim. We spent the day admiring one of the most amazing natural wonders in the world. I was imagining the impact the beauty was having on them, the rich cultural experience, and how they would remember this trip for the rest of their lives.
Or so I thought. When we returned, each of my boys had one thing to report about what they saw that day. The younger one said: “I pushed a button on a Coke machine and I got a free soda!” The older one said (while pointing to a spot on his lower back): "We saw a girl with hair this long!” Mom squinted her eyes at me as if to say “What did you guys really do today?”
The same is true with documentation. Often, writers believe they have produced one of the written wonders of the world but all that people remember is the trouble they had logging in to the system. Let us know what you take away from a journey through Informix documentation. After using the Informix Information Center, be sure to tell us the following:
And yes, we even want to know if you had trouble logging in.