Writing and Writers


Writing Home Page | KenjWagner.com Home Page

Vital information and articles related to writing.


The Top Five Mistakes That Companies Make with Regard to Technical Documentation


I've seen it time and again. One of the most common weaknesses that I've seen in engineering companies-indeed, an almost universal fault-is the lack of proper technical documentation. Some would laugh this off as a minor detail; however, the repercussions are often severe. A company's entire future can be made or lost based on the amount of attention they pay to this issue.

Over the years, I've identified five problems that I've found to be particularly common when it comes to writing technical documentation. I'd like to share these thoughts with you, in the hope of preventing others from falling down the same paths.

1. Not having any user manuals

Don't laugh. This may seem like a fairly basic mistake-absurd, even-but it is surprisingly common. I've encountered many companies that don't provide user manuals for their products, or whose manuals are skeletally thin or years out of date. In fact, I'd estimate that about half of the small engineering companies that I've encountered fall into this category. (Of course, one seldom encounters this problem when buying off-the-shelf software or consumer electronics. Amongst engineers though, it's a depressingly familiar story.)

I remember how one engineer told me why his company didn't provide any user manuals with their products. In hushed tones, he said, "It's because we don't make any money by writing manuals. It's not a money-making venture, so our management doesn't want to waste time on this." An annoyed expression crept into his face, then he leaned closer and said, "We have lost so many customers because we don't have decent documentation. Talk about being penny-wise, pound-foolish!"

It's not just the customers who suffer when manuals are inadequate or non-existent. What about the employees themselves? What happens when a new engineer comes on board, and has to learn quickly? Or what happens when existing engineers need to familiarize themselves more with unfamiliar aspects of their product lines? The user documentation, if properly written, can provide a gentle and efficient way of bringing the up to speed. Without it, they will be forced to rely more heavily on other engineers to educate them, thus wasting the time of everyone concerned. Weeks, if not months, of valuable manpower can be squandered in this fashion.

2. Not having proper internal documentation

It's not just the user documentation that companies fall short on. Internal documentation is frequently a casualty as well, as companies scramble to release a product. In their haste to bring products to market, companies often let their internal design documents fall hopelessly by the wayside.

It doesn't help that programmers and engineers are notorious for having lackluster communication skills, and that documentation is a task that they seldom enjoy. I've encountered many software companies, for example, whose software designs were an intractable mess due to their lack of architectural documents, interface descriptions and in-code comments. Sadly, I've seen similar problems when it comes to mechanical designs, electronic designs, manufacturing procedures? you name it.

I've spoken to engineers whose companies have either gone under, or have been teetering on the brink. Almost invariably, lack of adequate documentation has been a major factor in such situations.

I always tell my bosses and co-workers, "I want to make sure that my work is darned well documented. If I leave the company, or if I die in a car accident, for I want to make sure that this company can march on without me." That should be one of the prime reasons behind keeping thorough documentation-to make sure that the company won't be crippled by any person's absence.

Unfortunately, many employees take the opposite tack. They purposely scrimp on the documentation, thinking that this will ensure them some job security-and sometimes, this works. However, a smart employer knows that an engineer who documents well is worth far more than another engineer who keeps his cards close to his vest. The latter may be essential in the short term, but ultimately, he's a long-term liability.

3. Forgetting one's audience

This problem often occurs when developing user documentation. Programmers and engineers frequently forget that their manuals are going to be read by people who are unfamiliar with their products, or who don't have the same technical skills. I remember one company in particular-a machine controller company on the west coast. Their "user manual" was a horrible hodge-podge of acronyms, undefined terms and seemingly random thoughts, with about a dozen procedures listed in no particular order. Their user documentation lacked such basic details as how to start the controller up, or how to stop it in the case of an emergency-critical details that any neophyte user should expect to find in a manual.

A related problem is the failure to use proper language. Consider the case in which many of the readers are not native English speakers-say, when marketing a product in Europe or Asia, or when writing assembly procedures for foreign-born factory workers. In such cases, it may be necessary to keep the language fairly simple. If this is not possible-say, when discussing complex details that demand a great deal of precision-one can often compensate by adding some aptly-chosen charts, diagrams or photographs. Either approach can be helpful in making complex text a bit easier to absorb.

4. Not being suitably graphic

It's undeniably cliché, but true nonetheless-a picture does paint a thousand words. Similarly, a manual that makes judicious use of images and diagrams will be much easier to understand than one that is composed entirely of text descriptions.

Some consider this to be childish and unnecessary. I don't, and my experience has shown that the majority of users appreciate having these visual guides. Remember; no matter how sophisticated your readers are, they're still human. Even an intelligent, otherwise careful reader can accidentally miss some important detail, especially when pressed for time.

5. Not striving for excellence

It's interesting to see how programmers and engineers can strive for excellence in many aspects of their work, yet take the exact opposite approach when it comes to documentation. "Who cares about wording anyway?" I've heard many engineers say. "We're not writing poetry or screenplays here. What matters is that the documentation must be technically accurate."

This is an appallingly short-sighted view. Technical accuracy is indeed important, but so are presentation and style. Few engineers would listen to a job applicant who shows up in a bathrobe and slippers, or a litigation attorney who speaks like a valley girl-and yet somehow, these same engineers expect their fellow techies (or worse, a customer!) to slog through pages of meandering, poorly phrased text. Even matters as fundamental as spelling, grammar and proofreading are often treated as mere annoyances-piddling details that are worth nothing more than a cursory glance.

(To my relief, I have not encountered any such attitudes at my place of employment. I hasten to say this, lest anyone think that I'm complaining about the people that I work with! No, I've found that we all appreciate the value of excellence, for which I am always thankful. But I digress.)

Remember: When writing for one's fellow techies, one should bear in mind that they must often absorb voluminous amounts of information in scant amounts of time. When writing for laymen, one should make the text as gentle and easy to digest as possible, lest they become lost in an ocean of geekspeak. Either way, putting a little extra effort into matters of elegance and style can make a world of difference.

I won't go into detail about what constitutes good writing technique, as that would be beyond the scope of this text. Suffice to say that a good programmer or engineer should make sure that his writing is readable and well-organized, and that it flows smoothly from one topic to another.

I would be thrilled beyond belief if I never saw another slipshod manual, or if I never heard another story about companies collapsing due to non-existent documentation. A hopeless fantasy? Maybe. Still, I hope that some techies out there will read this message, and that they'll take it to heart.

About The Author

V. Berba Velasco has a doctorate in Electrical Engineering and has been plying his trade for nearly a decade. During that time, he has repeatedly discovered the importance of good technical writing, and the pitfalls that can occur from ignoring its value.

Dr. Velasco currently works as a senior electrical and software engineer for Cellular Technology Limited (http://www.immunospot.com, http://www.elispot-analyzers.de), a biotech company in Cleveland, Ohio. During his spare time, he raises dodo birds, builds human brains and plays with his collection of magnetic monopoles.


MORE RESOURCES:
table border=0 width= valign=top cellpadding=2 cellspacing=7trtd width=80 align=center valign=topfont style=font-size:85%;font-family:arial,sans-serifa href=http://news.google.com/news/url?sa=Tct=us/0i-0fd=Rurl=http://www.eonline.com/uberblog/b69550_new_x-men_getting_oc_treatment.htmlcid=1272117988ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNEANcUjjEz1bS_5TET1YbRKWxQ-0Qimg src=http://news.google.com/news?imgefp=N6W0d-LbTU8Jimgurl=images.eonline.com/eol_images/Entire_Site/20080723/425.jackman.xmen.072308.jpg width=80 height=59 alt= border=1brfont size=-2E! Online/font/a/font/tdtd valign=top class=jfont style=font-size:85%;font-family:arial,sans-serifbrdiv style=padding-top:0.8em;img alt= height=1 width=1/divdiv class=lha href=http://news.google.com/news/url?sa=Tct=us/0-0fd=Rurl=http://popwatch.ew.com/popwatch/2008/11/josh-schwartz-x.htmlcid=1272117988ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNGo54HSfG4qWhYg2Cj-uJlBnFABWQJosh Schwartz bwriting/b #39;X-Men#39; sequel: OMFG or WTF?/abrfont size=-1font color=#6f6f6fEntertainment Weeklynbsp;-/font nobr22 hours ago/nobr/fontbrfont size=-1And that#39;s why I#39;m more than a little perturbed by the news that Josh Schwartz (exec producer of GG, as well as The OC and Chuck) will be bwriting/b (and b.../b/fontbrfont size=-1a href=http://news.google.com/news/url?sa=Tct=us/0-1fd=Rurl=http://www.nytimes.com/2008/11/20/arts/20arts-001.html%3Fref%3Dartscid=1272117988ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNFfwqHskWQnqSj1KSb3i3WyDPHlxA‘X-Men’ Heads Back To Boyhood/a font size=-1 color=#6f6f6fnobrNew York Times/nobr/font/fontbrfont size=-1a href=http://news.google.com/news/url?sa=Tct=us/0-2fd=Rurl=http://www.empiremovies.com/index.php%3Fid%3D25039cid=1272117988ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNHgVD6hzXBZv7_Xm_nUzsymBgG6lgJosh Schwartz bWriting/b X-Men: First Class/a font size=-1 color=#6f6f6fnobrEmpire Movies/nobr/font/fontbrfont size=-1a href=http://news.google.com/news/url?sa=Tct=us/0-3fd=Rurl=http://geeksofdoom.com/2008/11/19/gossip-girl-writer-still-scripting-x-men-first-class-not-directing/cid=1272117988ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNH5CwkteZVF0aS7q4dEj55lwV40EA‘Gossip Girl’ Writer Still Scripting ‘X-Men: First Class’; Not b.../b/a font size=-1 color=#6f6f6fnobrGeeks of Doom/nobr/font/fontbrfont size=-1 class=pa href=http://news.google.com/news/url?sa=Tct=us/0-4fd=Rurl=http://www.eonline.com/uberblog/b69550_new_x-men_getting_oc_treatment.htmlcid=1272117988ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNEANcUjjEz1bS_5TET1YbRKWxQ-0QnobrE! Online/nobr/anbsp;- a href=http://news.google.com/news/url?sa=Tct=us/0-5fd=Rurl=http://www.firstshowing.net/2008/11/18/fox-moving-forward-with-gossip-girl-young-x-men-spin-off/cid=1272117988ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNGfZ0EdaKIqfhnd872p8__3YjcO2QnobrFirst Showing/nobr/a/fontbr/font class=p size=-1a class=p href=http://news.google.com/news?sourceid=navclientie=ISO-8859-1rls=GGLG,GGLG:2005-22,GGLG:enncl=1272117988hl=ennobrall 71 news articles/nobr/a/font/div/font/td/tr/table

table border=0 width= valign=top cellpadding=2 cellspacing=7trtd valign=top class=jfont style=font-size:85%;font-family:arial,sans-serifbrdiv style=padding-top:0.8em;img alt= height=1 width=1/divdiv class=lha href=http://news.google.com/news/url?sa=Tct=us/1-0fd=Rurl=http://hometownlife.com/article/20081120/LIFE/811200351/1106/NEWS13cid=1272586162ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNGyUpfFTUlQ88LhJeToHYbXGkbW0ANovi resident offers insight to world of bwriting/b/abrfont size=-1font color=#6f6f6fNovi News,nbsp;MInbsp;-/font nobr1 hour ago/nobr/fontbrfont size=-1By Kelly Murad • STAFF WRITER • November 20, 2008 quot;There#39;s A Book In You is bwriting/b in its simplest form,quot; said Durant, 72. quot;It#39;s about understanding the b.../b/font/div/font/td/tr/table

table border=0 width= valign=top cellpadding=2 cellspacing=7trtd valign=top class=jfont style=font-size:85%;font-family:arial,sans-serifbrdiv style=padding-top:0.8em;img alt= height=1 width=1/divdiv class=lha href=http://news.google.com/news/url?sa=Tct=us/2-0fd=Rurl=http://www.google.com/hostednews/ap/article/ALeqM5jQUZaPLYcXsZAbUiOd_xe7VbRprgD94I7Q7G0cid=1272355186ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNExYgVgDuPujMZQt6CEMCfmxt0KlgRapper gets 20 years after bwriting/b shooting song/abrfont size=-1font color=#6f6f6fThe Associated Pressnbsp;-/font nobr19 hours ago/nobr/fontbrfont size=-1DUBLIN, Ga. (AP) — He shot a man twice and felt so good about it, police said, a rapper wrote a song describing the shooting and calling out the victim by b.../b/font/div/font/td/tr/table

table border=0 width= valign=top cellpadding=2 cellspacing=7trtd valign=top class=jfont style=font-size:85%;font-family:arial,sans-serifbrdiv style=padding-top:0.8em;img alt= height=1 width=1/divdiv class=lha href=http://news.google.com/news/url?sa=Tct=us/3-0fd=Rurl=http://www.billboard.com/bbcom/news/article_display.jsp%3Fvnu_content_id%3D1003893924cid=1272368528ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNH7K7RArnmQDgjaKjuEmanNlvocEgOneRepublic bWriting/b For New Album/abrfont size=-1font color=#6f6f6fBillboard,nbsp;NYnbsp;-/font nobr21 hours ago/nobr/fontbrfont size=-1To celebrate the platinum success of its 2007 debut quot;Dreaming Out Loud,quot; OneRepublic was originally planning to reissue the album with bonus content in time b.../b/font/div/font/td/tr/table

table border=0 width= valign=top cellpadding=2 cellspacing=7trtd valign=top class=jfont style=font-size:85%;font-family:arial,sans-serifbrdiv style=padding-top:0.8em;img alt= height=1 width=1/divdiv class=lha href=http://news.google.com/news/url?sa=Tct=us/4-0fd=Rurl=http://www.delmarvanow.com/article/20081120/NEWS01/81120010/1002cid=1272551038ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNH2B76o6_heLchKOAvDFWnxzQZ4zgGEORGETOWN: Ex-trooper admits bwriting/b phony tickets/abrfont size=-1font color=#6f6f6fDelmarva Daily Times,nbsp;MDnbsp;-/font nobr4 hours ago/nobr/fontbrfont size=-1GEORGETOWN -- A former Delaware State Police trooper from Georgetown has pleaded guilty to charges he wrote phony traffic tickets to fictitious people. b.../b/font/div/font/td/tr/table

table border=0 width= valign=top cellpadding=2 cellspacing=7trtd valign=top class=jfont style=font-size:85%;font-family:arial,sans-serifbrdiv style=padding-top:0.8em;img alt= height=1 width=1/divdiv class=lha href=http://news.google.com/news/url?sa=Tct=us/5-0fd=Rurl=http://www.timesonline.co.uk/tol/news/world/asia/article5197439.ececid=1272548634ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNFhFZdPxCKTU0TeW4Zoz0iocj5OugTeenager murdered for bwriting/b love letter/abrfont size=-1font color=#6f6f6fTimes Online,nbsp;UKnbsp;-/font nobr3 hours ago/nobr/fontbrfont size=-1quot;The accused killed the boy for bwriting/b a love letter to a girl of the same village. There was a scuffle, and he was pushed in front of a train,quot; b.../b/font/div/font/td/tr/table

table border=0 width= valign=top cellpadding=2 cellspacing=7trtd valign=top class=jfont style=font-size:85%;font-family:arial,sans-serifbrdiv style=padding-top:0.8em;img alt= height=1 width=1/divdiv class=lha href=http://news.google.com/news/url?sa=Tct=us/6-0fd=Rurl=http://www.greenvilleonline.com/article/20081120/NEWS01/811200331/1071/YOURUPSTATE01cid=1272341092ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNGl9QRsTtq9A8rnRWoSqgfy0k4noQSimpsonville woman charged with bwriting/b bad checks for jewelry/abrfont size=-1font color=#6f6f6fGreenville News,nbsp;SCnbsp;-/font nobr9 hours ago/nobr/fontbrfont size=-1By Paul Alongi • STAFF WRITER • November 20, 2008 Greenville police are warning businesses to watch out for a Simpsonville woman who was charged Wednesday b.../b/font/div/font/td/tr/table

table border=0 width= valign=top cellpadding=2 cellspacing=7trtd valign=top class=jfont style=font-size:85%;font-family:arial,sans-serifbrdiv style=padding-top:0.8em;img alt= height=1 width=1/divdiv class=lha href=http://news.google.com/news/url?sa=Tct=us/7-0fd=Rurl=http://www.daily-times.com/ci_11027781cid=1272548632ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNF2oQXRi7u6yXCNmTj0J4NfM1h9sgBloomfield schools benefit from bwriting/b project/abrfont size=-1font color=#6f6f6fFarmington Daily Times,nbsp;NMnbsp;-/font nobr9 hours ago/nobr/fontbrfont size=-1By G. Jeff Golden The Daily Times As part of the Bisti bWriting/b Project, local artist Margaret Katirgis visited students at Blanco Elementary School this b.../b/font/div/font/td/tr/table

table border=0 width= valign=top cellpadding=2 cellspacing=7trtd valign=top class=jfont style=font-size:85%;font-family:arial,sans-serifbrdiv style=padding-top:0.8em;img alt= height=1 width=1/divdiv class=lha href=http://news.google.com/news/url?sa=Tct=us/8-0fd=Rurl=http://www.redbluffdailynews.com/news/ci_11022829cid=1272306922ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNHMJqBfoKZ2mLCK1nuj7byUQLCdfwFlournoy students use bwriting/b tool/abrfont size=-1font color=#6f6f6fRed Bluff Daily News,nbsp;CAnbsp;-/font nobr22 hours ago/nobr/fontbrfont size=-1FLOURNOY- Along with an investment in a one-to-one laptop ratio, Flournoy Elementary School piloted an Internet-based bwriting/b application from November 2007 b.../b/font/div/font/td/tr/table

table border=0 width= valign=top cellpadding=2 cellspacing=7trtd valign=top class=jfont style=font-size:85%;font-family:arial,sans-serifbrdiv style=padding-top:0.8em;img alt= height=1 width=1/divdiv class=lha href=http://news.google.com/news/url?sa=Tct=us/9-0fd=Rurl=http://www.businessweek.com/bschools/content/nov2008/bs20081118_490130.htm%3Fchan%3Dtop%2Bnews_top%2Bnews%2Bindex%2B-%2Btemp_business%2Bschoolscid=1271920639ei=x5MlSeX2GaGuyQTzv9jBAQusg=AFQjCNHtFMEEPe3j5S_pWpVAieyrXh7bQAMBA bWriting/b Tips/abrfont size=-1font color=#6f6f6fBusinessWeeknbsp;-/font nobrNov 18, 2008/nobr/fontbrfont size=-1By Alison Damast MBAs may be good at analyzing spreadsheets and reading financial statements, but many cringe when faced with a lengthy academic bwriting/b b.../b/font/div/font/td/tr/table

Writing - Google News



Writing Home Page | Writing Site Map | News | KenjWagner.com Home Page
EZmatic.com | Entertainment | Institutions | Loans | Hairstyles Pictures | Health | ZippyGo | TrafficFifh

KenjWagner.com - all Vital information and articles related to writing and writers.

© 2006