TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I was informed that our clients wanted more information on how to accomplish
a specific function in an extremely complex program. This is a program I've
documented since 1995, but it's still daunting to me -- even some of the
senior programmers get flummoxed by it. So after some meetings with the
programmers I finally understood the bizarre functionality and we hash out
what needs to be done. I wrote a detailed set of instructions and had it
QA'd by a senior programmer. He looked it over and said it was right, but I
should check with another programmer to verify a couple of things.
She looked it over and said I don't have it right. After a few minutes of
explanation, I realized I had no clue about how the process is supposed to
work, and got a bit depressed. I said we need to go through the actual
program - her explanations are making my head swim. So we opened the
program, and her explanation sounds like DBA-speak. I ask her to speak
User-speak, and we went through the process. It still made no sense.
Gnashing of teeth and rending of garments begins...
And then she realized that multiple columns in a Reference Table are
mislabeled. Oops. Not only that, but the pick lists associated with the
columns are from the wrong database tables. Mega-oops. This is a major
league bug, a bug for the ages. And it's been in this program since at
least 1994. And no one ever caught it, because no one bothers to use this
functionality because it's too complex.
"So," I asked her, "Do you want me to explain how it should work, but
doesn't, or do you want me to explain how it really works, but is wrong?" I
smiled as I said it.
You'd think I would have been peeved. Actually, it was one of the greatest
feelings I've had since I started TW'ing many years ago. I was going
bonkers trying to understand something, and now I realized it wasn't my own
inability to understand a program - this programmer was incredibly patient
with me - but rather a galactic flaw in the program.
So we worked out a method of getting this buggy functionality to produce the
results we want, and I documented the work-around. I also documented the
error, of course.
I have no idea what this proves -- except to not give up when you don't
understand something. I kept telling this programmer, "I still don't get
it." I felt pretty dopey, but ultimately a big problem was discovered.
Maybe in a few years it might actually get fixed, but in the meantime a User
can actually use this function.
Paul Strasser
Lafayette, Colorado 80026
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
