RE: Why Duplicate Efforts?

["Scudder, Beth" <beth -dot- scudder -at- retek -dot- com>]

	Paul Hanson (PHanson -at- Quintrex -dot- com <mailto:PHanson -at- Quintrex -dot- com> )
asks for opinions, anecdotes, and examples pertaining to the following
quote:

	"If a programmer has to write up a spec with the information that is
	used to create help text, why not have the programmer create the
help
	text? Why have a duplication of effort, since the help text is
	information from the specs? If a .hlp file is to be created, why
can't
	the Technical Writer just edit out the program changes,  like
changing
	calls from File A to File B (assuming the change has no impact on
the
	user), and have a .hlp file?"

I'm inclined to avoid having the programmers directly write the help text.

I give you Maclir's Rules of Software Development. Interestingly enough,
these were given to me by a programmer friend who works at the same company
as I do. These obviously don't cover it all, and it's a bit tongue-in-cheek,
but I think it does apply more than we would wish:

Maclir's rule #1: Programmers cannot write good English.

Now, it's not true, exactly, that programmers cannot write good English.
However, in almost every instance of specifications I have seen, the English
is ... lacking. The problems range from misspellings to passive voice to
unclear use of terminology to complicated, non-sequential procedures... and
so on. Sometimes these faults in the writing are due to ESL problems,
sometimes, to lack of time or interest. Some programmers I know can, if they
put effort into it, produce beautifully-written, clear specifications. But
in most cases, these specs are ground out with a minimum of time invested,
and the writing shows it.

That's what you have technical writers for. We read the specs and look at
the program and figure out what the programmer was saying. Because we have
technical expertise, access to programmers to answer our questions, the
program itself, and all of the backup documentation, we can figure this out.
That's the first half of that task. The second half is to then write this
information down in a way that will be clear to the user, who is bereft of
the aforementioned resources (except the program itself). If I directly
copied and pasted spec data into my Help files, the Help files would be very
difficult to comprehend... and that's not really the point of Help files, is
it?

Maclir's Rule #2: Documentation never gets written.

At my company, it's required that programmers write "Design Docs" as they
work. These design docs are intended to give the programmers direction, the
code reviewers a standard against which to review the code (X, Y, and Z are
on the design doc. Did they actually get accomplished?), and the
documentation group a source of information for the revised or new elements.
However, the programmers are not given much time to create these design
docs, and are not really recognized for their creation, even though it is
required that they create them. Most of our programmers are also bored silly
by creating these design docs. The result of this is that design docs get
written that contain virtually no information, or very little information. 

Most programmers that I've talked to and heard about see creating
documentation of any kind as boring and not their job. They generally seem
less than thrilled at the prospect of documenting code.

There's also the point that programmers get paid, in general, more than
technical writers. If the programmer is required to write the help, either
(1) the help will be just as convoluted, error-prone, etc. as the specs
were, or (2) the programmer will spend a fair amount of time fixing up the
specs to use them in the help. If the second case occurs, then wouldn't it
be monetarily more efficient to use the time of the lower-cost technical
writer to do that fixing up?

Maclir's rule #3: Any design documentation you find will be (a) Out of date;
(b) Plain wrong; (c) Missing the five crucial pages that explain the really
tricky bit; (d) All of the above.

That's another part of the technical writer's job, as I see it: to dig
through the mess and figure out what's right, what's wrong, what's
missing... fill in the gaps, fix the mistakes, and get it right. 

...Yup, it sounds to me a bit like I'm defending my job's right to exist. I
mean, if programmers wrote perfect, clear, easily comprehensible specs, and
liked doing it enough to do it on time despite the pressures of coding, I
would still be working in a book store. But at least where I work, things
aren't that way, and my job is all too secure.

Beth Scudder