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?