Documentation

simms_reporting

Documentation can be the most challenging detail about your software. If you’re not careful, documents can disintegrate into what is most often called doublespeak. In case you’re curious about the difference, the following is 100% pure doublespeak:

Any associated supporting element maximizes the probability of project success, yet minimizes cost and time required for the subjective decomposition criteria. Similarly, the interrelation of system and/or subsystem technologies presents extremely interesting challenges to anticipated fourth-generation equipment. Evidently, the incorporation of additional program constraints cannot be overemphasized when taking into account the subsystem compatibility testing. We can see, in retrospect, the use of hierarchical structures relating to resource ownership and allocation adds overriding performance constraints to the concept of program robustness. Specifically, the effectiveness of marginal isoquant analysis mandates operations-level consideration of the differentiation between requirements definition and object coordination. Notably, a large portion of interface coordination communication presents extremely interesting challenges to the not insignificant implementation limitations. Simply stated, the use of hierarchical structures relating to resource ownership and allocation cannot be overemphasized when taking into account assumptions that represent more than one interface. It is further assumed that any associated supporting element may only become apparent when we explicitly design the preliminary qualification limit. Without going into the technical details, a correct and consistent dual description of an abstract interface is not free to define the principles of effective resource management. Interestingly enough, the characterization of specific criteria recognizes other systems’ importance and the necessity for overall program marketability.

While hounds of language and comedy like me can derive many an hour of head-shaking chuckles from paragraphs like the one above, most ‘normal’ folks will just close such a document and never trust the program or its creators ever again. I’m hoping that your written materials speak not to the person below the lowest common level of understanding, but instead take their time to achieve their ideal purpose — explaining things when necessary, leading the reader through simple, definite steps of the process. Please let this last concept — process — be foremost in your mind as your guided tour through the software continues. Process is the only reason for software in the first place. If your software is not usable with ease, then it is the fault of the designer, who for some galling reason has adopted the idea that to make something deliberately beautiful with “cool” noises and a cutting-edge new look is the ultimate dream. For a user, however, they just want software that WORKS — something whose use saves them time, effort or, ideally, both. It can be covered in warts and smell like an old gym sock, but if it works, users will rave about how endearing the old clunker is.

Documenting something that works is the easiest situation known to any technical writer. ‘See how when you click this button,’ the documents narrate, ‘that you instantly get the information you need’. Talk about a dream job: writing the obvious for those who have never used the program before. Perfection and simplicity itself. It’s a far scream from educating someone on some new window, where most often you’re telling everyone to ignore the pretty panel that either slides, glides or cartwheels as they are trying to create a one-page printout of salient data that the boss wanted 10 minutes ago. Give me obvious process and time-saving productivity and I will extoll a program’s glories to anyone and everyone. But give me something made only to impress the aesthetes that at its core says ‘hang the clock and the outbox, just sit and marvel at my lusciousness’, and that probably expensive application will sit in my — and everyone else’s — programs list un-opened, un-used, and un-respected.

The KISS principle will always be foremost in the minds of anyone who assesses new software, or any new version of familiar applications. Remember the old joke “Men are easily distracted by bright, shiny objects”? It was never accurate. It should have read “Boys”. For two generations that have grown up without both literature and radio — to put a point on it, without much narrative or personal imagination — it seems that everything must now move (or better yet, shake), pop, do a slow reveal to some cool drum track that lasts no more than 1.8 seconds, or in some other way DAZZLES. This is a great concept if the designer’s desired goal is to entertain us, through a game or some other time-consumer; such is perfection if one is waiting for a bus or while inching along in a slow-moving check-out line.

But on the job, we just need tools; tools with which to bend time to our advantage and actually achieve something. Once the work is done, then have fun in any way that your pocket-sized babysitter can provide. But I have seen enough under-30s at their jobs engaged in text messaging, Facebooking and tweeting to wonder what their actual jobs are. If they are not employed as social media marketers then do their bosses know what they are up to with all that clicking and flicking? There are plenty of employers out there who have learned the hard way, and they have fired these “thumbers” (who hitchhike their way along the information highway, sharing everything from favorite restaurant menus, plans for the weekend to their most-favored makes and colors of condoms). One young friend who celebrated a new job as a filing clerk by initiating a week-long sequence of joke emails, gag texts, doodles and WTF photos, found himself being interviewed for jobs elsewhere after only two weeks, owing to a growing foot-high stack of files that sat untouched on the corner of his “actual” desktop.

To be divinely loquacious for a minim (an admiring nod here to Stephen Fry) for those who prefer the pretty over the practical and the stylistic over the the substantial, I acknowledge that gadgets and apps of the more pomaceous manufacture are a good avenue for fun and leisure. However, I will always favor the ‘short socks’ that help me get my work done using an amazing variety of software that runs on customizable hardware and platforms that don’t force me to choose between their purchase price and the skipping of a mortgage payment.

A friend who has only ever used computers of the pomaceous variety — yes, there’s that word again…look it up — is likewise irritated at the expense of every little custom doodad that he needs to do even the most basic things. He said, “Here’s what you do. First, you round off every corner. Next, you find a piece of some gaudy pastel-colored plastic and you take a belt sander to it until you can almost see through it. Last, glue it to other similarly-treated hunks of plastic and BANG, call it an “I” somethingorother. Mark the whole thing up by a thousand percent and find some poor ditz like me to buy it cuz it’s purty.” I couldn’t have said it better myself. I, however, go one step further and wonder how by now that is has not suffered the same fate as another unnecessary and popular mass of plastic: the hulahoop. Long after we are gone, I’m certain that in museums of popular culture children will walk by a shelf where there will sit, side-by-side, an iPhone and a GameBoy, and irritated parents will constantly have to remind the kiddies which is which. Why, because the iPhone is a bad product? No. It’s because leisure toys can never replace such tools of substance that sit on the museum shelf directly above them: the pen and the camera.

Despite an item’s “fun quotient”, it will be more fondly remembered for its pragmatic contribution to answering a life-long question: does it actually help me achieve something? Does it aid in taking action and getting something done? The writing of documentation should have the same goal — to help the reader ‘just get on with it’ WITHOUT distraction.

I mention the distraction factor because just today I asked a very productive friend if I could see his iPhone. The screen loaded and two particular apps fired up on his main screen — one that showed the weather and temperature outside and one that produced an instant GPS reading of his phone’s location. Being that he has worked in the same corner office for more than eight years, sitting next to the same open window, I asked him the prime use he has for the phone, since the two apps are, to say the least, completely redundant. Before he could answer the phone played a tune, and he grabbed it and said “Ah, I have a meeting. See you later”. On my way past his desk to head home, I noticed a Post-It note on his desk that showed the details of the very same meeting he had just dashed to attend. Perhaps the answer he didn’t have time to give me was the phone’s instructions on the optimum route to take to the meeting. As with a reader of good documentation, I’ll ask the fitting question now in closing: would it be the Post-It or the iPhone that would be classified as THE reason he made the meeting on time?

simms_jargon

The Corporate Employee

SIMMS_clock

You Know You Work in Corporate America When:

  • Art involves a white board.
  • Being sick is defined as can’t walk or you’re in the hospital.
  • Change is the norm.
  • Communication is something your group is having problems with.
  • Dilbert cartoons hang outside every cube.
  • Free food left over from meetings is your main staple.
  • Fun is when issues are assigned to someone else.
  • It’s dark when you drive to and from work.
  • Nepotism is encouraged.
  • Salaries of the members on the Executive Board are higher than all the Third World countries’ annual budgets combined.
  • The company logo on your badge is drawn on a post-it note.
  • The only reason you recognize your kids is because their pictures are hanging in your cube.
  • Vacation is something you roll over to next year or a check you get every January.
  • Weekends are those days your spouse makes you stay home.
  • When 100% of your time means 20 hours.
  • When someone asks about what you do for a living, you lie.
  • You get really excited about a 2% pay raise.
  • You know you’re working in corporate America when…
  • You learn about your layoff on CNN.
  • You only have makeup for fluorescent lighting.
  • You see a good-looking person and know it is a visitor.
  • You sit in a cubicle smaller than your bedroom closet.
  • You think lunch is just a meeting to which you drive.
  • Your biggest loss from a system crash is that you lose your best jokes.
  • Your boss’ favorite lines are “when you get a few minutes”, “in your spare time”, “when you’re freed up”, and “I have an opportunity for you.”
  • Your company welcome sign is attached with Velcro.
  • Your relatives and family describe your job as “works with computers”.
  • Your resume is on a diskette in your pocket.
  • Your supervisor doesn’t have the ability to do your job.
  • You’re already late on the assignment you just got.
  • You’ve sat at the same desk for 4 years and worked for three different companies.
  • You read this entire list and understood it.

 

“What publishers are looking for these days isn’t radical feminism. It’s corporate feminism a brand of feminism designed to sell books and magazines, three-piece suits, airline tickets, Scotch, cigarettes and, most important, corporate America’s message, which runs: Yes, women were discriminated against in the past, but that unfortunate mistake has been remedied; now every woman can attain wealth, prestige and power by dint of individual rather than collective effort.” — Susan Gordon

 

Leaders of the Free World

Some Leaders of the Free World sound like they were built for the job, while others do not…

“Eighty percent of air pollution comes from plants and trees.” – Ronald Reagan

“Every gun that is made, every warship launched, every rocket fired signifies in the final sense, a theft from those who hunger and are not fed, those who are cold and are not clothed. This world in arms is not spending money alone. It is spending the sweat of its laborers, the genius of its scientists, the hopes of its children. This is not a way of life at all in any true sense. Under the clouds of war, it is humanity hanging on a cross of iron.” – Dwight Eisenhower

“For those who like this sort of thing, this is the sort of thing they like.” – Abraham Lincoln

“Let us, then, fellow citizens, unite with one heart and one mind. Let us restore to social intercourse that harmony and affection without which liberty and even life itself are but dreary things. And let us reflect that having banished from our land that religious intolerance under which mankind so long bled, we have yet gained little if we countenance a political intolerance as despotic, as wicked, and capable of a bitter and bloody persecution.” – Thomas Jefferson

“Freedom is not enough.” – Lyndon B. Johnson

“The divinity of Jesus is made a convenient cover for absurdity. Nowhere in the Gospels do we find a precept for Creeds, Confessions, Oaths, Doctrines, and whole carloads of other foolish trumpery that we find in Christianity.” – John Adams

“If you think the United States has stood still, who built the largest shopping center in the world?” – Richard M. Nixon

“When more and more people are thrown out of work, unemployment results.” – Calvin Coolidge

“We are citizens of the world: and the tragedy of our times is that we do not know this.” – Woodrow Wilson

The very best luck and success to all of them in the future — they will need our help.

It’s the Law…

simms_justice

An engineer dies and reports to the pearly gates. St. Peter checks his dossier and says, “Ah, you’re an engineer – you’re in the wrong place.”

So the engineer reports to the gates of Hell and is let in. Pretty soon, the engineer gets dissatisfied with the level of comfort in Hell, and starts designing and building improvements. After a while, they’ve got air conditioning and flush toilets and escalators, and the engineer is a pretty popular guy.

One day God calls Satan up on the telephone and says with a sneer, “So, how’s it going down there in Hell?” Satan replies, “Hey, things are going great. We’ve got air conditioning and flush toilets and escalators, and there’s no telling what this engineer is going to come up with next.”

God replies, “What?! You’ve got an engineer? That’s a mistake – he should never have gone down there; send him up here.”

Satan says, “No way. I like having an engineer on the staff, and I’m keeping him.”

God says, “Send him back up here or I’ll sue.”

Satan laughs uproariously and answers, “Yeah, right. And just where are YOU going to get a lawyer?”

—————————-

An attorney was defending his client against a charge of first-degree murder.

“Your Honor, my client is accused of stuff his lover’s mutilated body into a suitcase and heading for the Mexican border. Just north of Tijuana a cop spotted her hand sticking out of the suitcase. Now, I would like to stress that my client is not a murderer. A sloppy packer, maybe…”

—————————-

An employer was asked to write a recommendation for a worker who was leaving and was not known for putting out a great deal of effort while on the job. Since the employer did not want to lie and make this person better than he was, he thought a while before writing anything.
Finally, he found just the right words:
“You would indeed be fortunate to get this person to work for you.”

—————————-

“Any medium powerful enough to extend man’s reach is powerful enough to topple his world. To get the medium’s magic to work for one’s aims rather than against them is to attain literacy.”

– Alan Kay, Scientific American

Where Am I?

simms_noScan

A man in a hot air balloon realized he was lost. He reduced altitude and
spotted a woman below. He descended a bit more and shouted, “Excuse me,
can you help me? I promised a friend I would meet him an hour ago, but I
don’t know where I am.”

The woman below replied, “You’re in a hot air balloon hovering
approximately 30 feet above the ground. You’re between 40 and 41 degrees
north latitude and between 59 and 60 degrees west longitude.”

“You must be an engineer,” said the balloonist.

“I am,” replied the woman, “How did you know?”

“Well,” answered the balloonist, “everything you told me is, technically
correct, but I’ve no idea what to make of your information, and the fact
is I’m still lost. Frankly, you’ve not been much help at all. If anything,
you’ve delayed my trip.”

The woman below responded, “You must be in Management.”

“I am,” replied the balloonist, “but how did you know?”

“Well,” said the woman, “you don’t know where you are or where you’re
going. You have risen to where you are due to a large quantity of hot air. You made a promise which you’ve no idea how to keep, and you expect people beneath you to solve your problems. The fact is you are in exactly the same position you were in before we met, but now, somehow, it’s my fault.”

Tidbits of Wisdom

simms_wisdom

Cryptotechnophobia: The secret belief that technology is more of a menace than a boon.

———————————————-

An Owner’s Manual by Dave Barry, from his Read This First!’:
“Congratulations! You have purchased an extremely fine device that would give you thousands of years of trouble-free service, except that you undoubtedly will destroy it via some typical bonehead consumer maneuver. Which is why we ask you to PLEASE FOR GOD’S SAKE READ THIS OWNER’S MANUAL CAREFULLY BEFORE YOU UNPACK THE DEVICE. YOU ALREADY UNPACKED IT, DIDN’T YOU? YOU UNPACKED IT AND PLUGGED IT IN AND TURNED IT ON AND FIDDLED WITH THE KNOBS, AND NOW YOUR CHILD, THE SAME CHILD WHO ONCE SHOVED A POLISH SAUSAGE INTO YOUR VIDEOCASSETTE RECORDER AND SET IT ON FAST FORWARD, THIS CHILD ALSO IS FIDDLING WITH THE KNOBS, RIGHT? AND YOU’RE JUST NOW STARTING TO READ THE INSTRUCTIONS, RIGHT??? WE MIGHT AS WELL JUST BREAK THESE DEVICES RIGHT AT THE FACTORY BEFORE WE SHIP THEM OUT, YOU KNOW THAT?”

———————————————-

Our documentation manager was showing her 2 year-old son around the office. He was introduced to me, at which time he pointed out that we were both holding bags of popcorn. We were both holding bottles of juice. But only he had a lollipop.
He asked his mother, “Why doesn’t HE have a lollipop?”
Her reply: “He can have a lollipop any time he wants to. That’s what it means to be a programmer.”

———————————————-

Important Questions…
If Americans throw rice at weddings, do Chinese throw hot dogs?

Was Robin Hood’s mother known as Mother Hood?


What do they call a coffee break at the Lipton Tea Co.?

How do you explain counter-clockwise to someone with a digital watch?


———————————————-

PARKINSON’S LAWS
Parkinson’s First Law: Work expands so as to fill the time available for its completion.

Parkinson’s Second Law: Expenditure rises to meet income.

Parkinson’s Third Law: Expansion means complexity and complexity means decay; or to put it even more plainly – the more complex, the sooner dead.

Parkinson’s Fourth Law: The number of people in any working group tends to increase regardless of the amount of work to be done.

Parkinson’s Fifth Law: If there is a way to delay in important decision, the good bureaucracy, public or private, will find it.

Parkinson’s Law of 1000: An enterprise employing more than 1000 people becomes a self-perpetuating empire, creating so much internal work that it no longer needs any contact with the outside world.

LAST ONE…

“During my eighty-seven years I have witnessed a whole succession of technological revolutions. But none of them has done away with the need for character in the individual or the ability to think.” — Bernard M. Baruch

Business Success…Sort Of

simms_businessPlan

There are in business three things necessary — knowledge, temper and time.

— Feltham

———————————————————————

There were in the USA two very large monopolies. The larger of the two had the following record: the Vietnam War, Watergate, double-digit inflation, fuel and energy shortages, bankrupt airlines, and the eight-cent postcard. The second was responsible for such things as the transistor, the solar cell, lasers, synthetic crystals, high fidelity stereo recording, sound motion pictures, radio astronomy, negative feedback, magnetic tape, magnetic “bubbles”, electronic switching systems, microwave radio and TV relay systems, information theory, the first electrical digital computer, and the first communications satellite.

Guess which one got to tell the other how to run the telephone business?

———————————————————————

SNIGLET OF THE DAY…

Carperpetuation (kar’ pur pet u a shun): The act, when vacuuming, of running over a string at least a dozen times, reaching over and picking it up, examining it, then putting it back down to give the vacuum one more chance.

— Rich Hall

———————————————————————

The owner of a large furniture store in the mid-west arrived in France on a buying trip. As he was checking into a hotel he struck up an acquaintance with a beautiful young lady. However, she only spoke French and he only spoke English, so each couldn’t understand a word the other spoke. He took out a pencil and a notebook and drew a picture of a taxi. She smiled, nodded her head and they went for a ride in the park. Later, he drew a picture of a table in a restaurant with a question mark and she nodded, so they went to dinner. After dinner he sketched two dancers and she was delighted. They went to several nightclubs, drank champagne, danced and had a glorious evening. It had gotten quite late when she motioned for the pencil and drew a picture of a four-poster bed. He was dumbfounded, and has never been able to understand how she knew he was in the furniture business.

Safety First

toon908

In a west Texas town, employees in a medium-sized warehouse noticed the smell of gas. Sensibly, management evacuated the building, extinguishing all potential sources of ignition — lights, power, etc.
After the building had been evacuated, two technicians from the gas company were dispatched. Upon entering the building, they found they had difficulty navigating in the dark. To their frustration, none of the lights worked. Witnesses later described the scene of one of the technicians reaching into his pocket and retrieving an object that resembled a lighter. Upon operation of the lighter-like object, the gas in the warehouse exploded, sending pieces of it up to three miles away. Nothing was found of the technicians, but the lighter was virtually untouched by the explosion. The technician that was suspected of causing the explosion had never been thought of as “bright” by his peers.

—————————–

Picasso was burgled and did a drawing of the robbers. The police arrested a horse and two sardines.

—————————–
PHRASEOLOGY FROM THE ’00S

Blamestorming: Sitting around in a group, discussing why a deadline was missed or a project failed and who was responsible.

Irritainment – Entertainment and media spectacles that are annoying, but you find yourself unable to stop watching them. The O.J. trials were a prime example.

Percussive Maintenance: The fine art of whacking the crap out of an electronic device to get it to work again.

Treeware: Hacker slang for documentation or other printed material.

Alpha Geek: The most knowledgeable, technically proficient person in an office or work group. “Ask Larry, he’s the alpha geek around here.”

Vulcan Nerve Pinch: The taxing hand position required to reach all the appropriate keys for certain commands. For instance, the warm reboot for a Mac II computer involves simultaneously pressing the Control key, the Command key, the Return key and the Power On key.

Yuppie Food Stamps: The ubiquitous $20 bills spewed out of ATMs everywhere. Often used when trying to split the bill after a meal: “We owe $8 each, but all anybody’s got is yuppie food stamps.”

A Surprising Solution to a Mystery

simms_probsolving

It’s common practice in England to ring a telephone by signaling extra voltage across one side of the two wire circuit and ground. When the subscriber answers the phone, it switches to the two wire circuit for the conversation. This method allows two parties on the same line to be signaled without disturbing each other.

One day an elderly lady with several pets called to say that her telephone failed to ring when her friends called; and that on the few occasions when it did ring her dog always barked first. The telephone repairman proceeded to the scene, curious to see this psychic dog. He climbed a nearby telephone pole, hooked in his test set, and dialed the subscriber’s house. The phone didn’t ring. He tried again. The dog barked loudly, followed by a ringing telephone. Climbing down from the pole, the telephone repairman found:

a. A dog was tied to the telephone system’s ground post via an iron chain and collar.

b. The dog was receiving 90 volts of signaling current.

c. After several such jolts, the dog would start barking and urinating on the ground.

d. The wet ground now completed the circuit and the phone would ring.

Moral: Some problems just require more moisture.

———————————-

MORE CANNY MARKETING…

When Braniff translated a slogan touting its upholstery, “Fly in leather,” it came out in Spanish as “Fly naked.”

Coors put its slogan, “Turn it loose,” into Spanish, where it was read as “Suffer from diarrhea.”

Chicken magnate Frank Perdue’s line, “It takes a tough man to make a tender chicken,” sounds much more interesting in Spanish: “It takes a sexually stimulated man to make a chicken affectionate.”

When Vicks first introduced its cough drops on the German market, they were chagrined to learn that the German pronunciation of “v” is f – which in German is the guttural equivalent of “sexual penetration.”

Not to be outdone, Puffs tissues tried later to introduce its product, only to learn that “Puff” in German is a colloquial term for a whorehouse. The English weren’t too fond of the name either, as it’s a highly derogatory term for a non-heterosexual.

A hair products company, Clairol, introduced the “Mist Stick”, a curling iron, into Germany only to find out that mist is slang for manure.

When Gerber first started selling baby food in Africa, they used the same packaging as here in the USA – with the cute baby on the label. Later they found out that in Africa companies routinely put pictures on the label of what’s inside since most people can’t read.

Mutual Benefit Is the Anchor of Good Business

kcsi_math

Nonbelievers
Author Sinclair Lewis was at home one morning in November 1930, when the telephone rang and a voice with a Swedish accent informed him that he had been awarded the Nobel Prize in Literature.

The caller identified himself as a newspaperman, but the novelist thought he was being ribbed by a friend who liked to do imitations.

“Very funny,” he said, ”And who else do you impersonate?”

The caller finally convinced the writer that he wasn’t kidding. Lewis went wild with excitement. He phoned his wife, Dorothy Thompson, and shouted into the mouthpiece:

“Dorothy, I’ve won the Nobel Prize!”

“Very funny,” she replied, ”and I’ve been awarded the Order of the Garter.”

Mutual Aid
As a Chicago sportswriter, Ring Lardner covered the White Sox at home and on the road.

The team had a rookie pitcher of limited schooling, who was deficient in reading and writing. When he was in the dining car on the train, he would pretend to study the menu, but invariably would end up ordering ham and eggs.

Lardner felt sorry for him and made it a point to occupy the same table. He would do some pretending, too. He would read the menu aloud and pretend that this was what he was in the habit of doing.

A friendship developed between the two, which proved to be mutually beneficial. The rookie learned the pleasures of a varied diet and Lardner became famous writing about his tablemate’s experiences.

~ NEWS ITEM ~
In February 1995, a fishing boat sank in rough, cold waters off Vancouver Island, leaving two men in a life raft that was tied to the sinking boat by a nylon rope. Neither had a knife to cut the rope, and had the ship sunk, it would have pulled the boat and the men down with it. For an hour, the two men alternated chewing the rope, with one man losing a tooth in the process and, minutes before the ship sank, the men finally chewed through the rope and survived.