Kirrily Skud Robert <[EMAIL PROTECTED]> wrote:
> On Tue, Dec 05, 2000 at 11:05:43AM -0800, Steve Fink wrote:
> > David Grove wrote:
> >
> > > Also, as far as documentation goes, I think it _should_ be written
by
> > > apprentices, so that non-masters can understand it too. That's
always
> been
> > > a huge criticism of the perldocs. That's not grunt work. That's
proper
> > > allocation of duties to the best suited personnel for the benefit
of
> the
> > > project.
> >
> > Except it's a particular duty that nobody really likes to perform.
Which
> > pushes it into the realm of grunt work.
>
> Bah. *I* like documenting.
Yeah. Haven't you noticed some of the sizes of my posts? Typing fast
helps. Not everybody hates it, especially since perl doc tends to let
people show a slight perlish 'tude... not to mention make up a word now
and then.
("whipuptitude" -- a la Larry)
;-))
I'll reiterate though. Initial documentation, be it basic notes or
whatever, have to be done by the programmer. Any technical writer (it's a
profession) will tell you that. The apprentice will only be able to
expand, and only expand within his own capabilities. Unless the skill is
already in his brain, he'll need something to work from, and the "master"
will have to do some proofreading (also tedious) no matter what. If the
skill is already in the apprentice's brain, he's not apprentice material,
and should be apprenticing someone else. The counterargument of "following
closely and paying attention will be enough" (I expect someone to say
this) works only to a point.
I'm not griping about anything. I'm just advising from the point of view
of someone who knows some of the pains of technical writing.
