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.
Sandy Harris reports: <<At one point I had access to 600,000 or so
lines of a client's C code, so I wrote a few little grep scripts to
test it a bit. Results were appalling. It was production code, but
only used as internal test tools; it wasn't what they shipped to
customers.>>
Apalling doesn't surprise me. I don't get the impression that the
people who teach programming courses spend enough time on quality
assurance, or that the people who employ the programmers care enough
to give them the time to do the job right. I may be doing the
teachers an injustice, but the results speak for themselves: anyone
who uses modern software is all too familiar with shoddy coding.
C strikes me as an example of language or compiler designers being
far too clever for their own good, and insufficiently concerned with
the real-world conditions under which software is created and used.
I'm way out of date on this, so please correct me if I'm wrong, but
one of the big flaws in C is that it doesn't have "automatic garbage
collection" (originally billed as one of the huge advantages of
Java), and this was one reason why so many C programs developed fatal
memory leaks. In any event, many memory leaks are simple human error:
failing to deallocate memory when you allocate it. That's about as
smart as writing an interative loop without remembering to add the
terminator (e.g., FOR without NEXT, DO without UNTIL).
C'mon, guys: isn't this why we invented computers (to automate things
that humans can't be relied upon to do right)?
<<If you do check code this way, what should you do with your
results? I considered passing them on to the programming manager, but
did not do it. I figured as a contractor and "only" a tech writer, it
was not a good idea to stir things up that way.>>
You should reconsider that approach. First, if those of us who are
aware of problems don't speak up, those problems go unsolved.
Sometimes the consequences are trivial, sometimes they're major and
potentially fatal. The problem with lazy programming is that it
becomes a habit, and that habit leaks into the production code. When
it does... I've seen this happen with editors, so I can only imagine
it happens worse with programmers faced with insane deadlines.
Second, pointing out problems is one of the best ways for us to earn
respect from our colleagues. The trick, of course, is to reveal the
problems in a helpful way, not in an "I'm smarter than you and you
should be fired" way. (That is, unlike the way I've described
programmers above. Sorry for the rant!) That's doubly true in China,
where mianzi enters into the problem: you can't risk making someone
look foolish in public. Even so, I've certainly heard tales of even
careful bearers of bad news being punished instead of rewarded.
Instead, it may be worth your while talking to the specific
programmers who created the problem (if you can identify them) or to
each programmer individually, if you can make the time. Then, the
goal becomes one of making them look good (i.e., improving their
mianzi) at the next performance appraisal. For example, what if you
offered them your grep code or a customized version of it so that
they could find such problems themselves simply by running the code?
I've done similar things with authors by writing performance-support
tools to help them find recurring problems in their writing before
anyone else ever sees the problem.
Is this just empty theory, or does it actually work? Can't say for
programmers as a group. I do know firsthand that it works great with
most of my 95 Chinese clients and a couple hundred Japanese clients
(all researchers at major universities), and worked well with the two
programmers at my last job. That's only one data point (me) that I
hope others can expand upon.
----------------------------------------------------
-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
www.geoff-hart.com
--------------------------------------------------
***Now available*** _Effective onscreen editing_
(http://www.geoff-hart.com/home/onscreen-book.htm)
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
