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.
Subject:Re: Code Documentation From:"Steven J. Owens" <puff -at- NETCOM -dot- COM> Date:Thu, 5 Nov 1998 22:21:08 -0800
Mike,
> There are few things as annoying, when reading code left behind by the last
> programmer, as line after line of documentation that restates what the code
> says, but never mentions why the code is there in the first place, or how it
> fits in the grand scheme of things.
Just as annoying when I find it user guides; command descriptions
like "The File...Save command saves the file". are incredibly
annoying. I know why they end up in the guide - I've been there
myself:
It's the week before you have to shove the book out the door to
get it printed in time for the ship date, you're *still* waiting
for a clear explanation of the menu from the developer, anything
you write will the authoritative reference and you have to write
*something* or your boss will give you all kinds of grief about
it!
...and the developer never gets back to you before the end of the
week, so it ends up going out with that text. Understandable, but
still annoying when you're up at 4 in the morning trying to find
something that'll explain how the application *works*.
Seeing it in comments is just as annoying; I can see the code is
setting the blah variable to 4, but what I want to know is *why*
it's doing it...
> Side note on the example: the rather copious use of the word "instantiate"
> is a case of knowing the audience. For programmers, there is nothing at all
> wrong with the word, and it is the right word. At this point in a program,
> there is typically a lot of instantiating going on, so the word gets used a
> lot. You could do a "sportscaster" on it, but that would take a long time to
> write and annoy the reader.
Instantiate - "create an instance of". It's a very logical (if a
bit hard to say) term that the Object Oriented Programming field came
up with. OOP defines classes of objects and their behaviors, then
creates instances of the classes in the system, and starts them
interacting. In many ways it's analogous to initialize ("define the
existence of and usually the initial value of a variable), as used in
more classical programming terminology.
