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.
There is a very bad practice "out there" that some developers use. It is
called "QA by Compilation." In other words, if the code compiles, then it
works.
Here is a true e-mail exchange between me and a developer (at a previous
company, of course), edited for space and anonymity:
Me: O Great Developer Person, I noticed that the whizbang feature does not
bang, is this a known issue, or should I file a bug on it?
Developer: Huh? What are you talking about? There are no bugs in the
whizbang feature.
Me: Well, I thought it was supposed to do this, but it does not seem to.
Perhaps I am doing something wrong.
Developer: Well, tell me the exact sequence of steps you took, and I will
see if I can reproduce the bug. But you probably did something wrong.
Me: Okay. Open the application and try to use whizbang. It fails.
Developer: <nothing back from the developer for 2 hours, so I called>
Me: Were you able to reproduce the problem?
Developer: Yes. I filed a bug. Mumble mumble version control mumble mumble
it compiled.
(END of TRUE STORY)
Hell, I can write code that compiles. I have. Does not mean that it works.
(It didn't--my app did not do anything--but it did not crash, either, so I
probably could have made some money with that code if I had more marketing
savvy and lower ethical standards).
So, I am definitely in the camp of USE THE PRODUCT YOU ARE DOCUMENTING. For
software products, that should be fairly easy. For things like medical
devices for extracting brain tumors, try to arrange for a demonstration. Or
find a coworker that you do not like so much to try it out on. Heavy
machinery--again a demo would be good. More fun if you get to operate it.
Finally, trusting the specs in the software industry will lead to heartache.
Don't just pretty up the specs. You may be prettying up fiction.
Sorry, I would be more vitriolic and verbose about this, but it is time to
go home. Maybe tomorrow.
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See http://www.infomap.com or 800-463-6627 for more about our solutions.
---
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.
