Re: Tech documentation (Re: Perl Apprenticeship Program)
Kirrily Skud Robert [EMAIL PROTECTED] wrote: On Tue, Dec 05, 2000 at 11:28:31AM -0800, Nathan Wiger wrote: Anyways, that's just one suggestion. Do I have any idea where to find these mythical people? No, unfortunately. Perhaps some feelers on newsgroups might be a good place to start. Personal experience shows that this could be a win, though. Open Source Writers Group (http://oswg.org/) is a good starting point. I'm subscribed to their mailing list. I can think of a couple of other good places to try, too, but they're a bit politically incorrect to mention in this context :-/ K. Apologies to this author. I didn't know he was a she, and I mean no offense at my guess at what group was politically incorrect. It just looked like Dan had seen the link and missed a bit later on. Of course realizing that documentation is good no matter where it comes from, I think we need to scour around on the inside as much as possible before looking to "outsource". Perl writing has a sort of unique humor (and odd linguistics "perlisms"), which has helped to form and identify the culture. I think it would be a shame to lose that if we pawn off too much onto people not "into" the culture. I won't discount her suggestion though. Any documentation is good documentation, especially on behalf of programmers.
Re: Perl Apprenticeship Program
On Tue, 5 Dec 2000, 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 Except it's a particular duty that nobody really likes to perform. Which Actually, I kinda like it. If someone is willing to answer my questions so that I understand what it is I'm documenting, I'm willing to do a good chunk of the documentation. I'm currently working on some docs on handling binary data in Perl (with pack, unpack, vec, etc) that I intend to submit to perl.com. Dave
Re: Perl Apprenticeship Program
Today around 11:55am, David Grove hammered out this masterpiece:
: Don't miss the point. I'm not proposing to look for masters using
: brainbench, but for viable apprentices that way. Basic Perl skill seems a
: certian criterium for candidacy, as would basic c skill for some areas.
: I've also ranked master there, but only in Perl, not perlguts. I've
: proposed using the tests in my company for potential employees, because if
: nothing else it can help identify people who do RTFM. Basically, at the
: minimalest, it could dispell fears by masters that they would end up with
: apprentices wanting to learn basic CGI. It seems logical that we could get
: more master-volunteers if we can help to assure them they won't be working
: with ... well, with someone with desire but no frame of reference. (I
: think that's politically correct.) Remember, the purpose of this
: apprenticeship is to help people who are not familiar with perl internals
: become so. Requiring familiarity with perl internals as a criterium for
: candicacy for learning basic familiarity with perl internals is not
: logical [logic error: infinite loop].
Point taken. :-)
: If your message was intended as private, sorry for going public. I wanted
: to make this clarification.
No, it was public and you made a good clarification.
--
print(join(' ', qw(Casey R. Tweten)));my $sig={mail='[EMAIL PROTECTED]',site=
'http://home.kiski.net/~crt'};print "\n",'.'x(length($sig-{site})+6),"\n";
print map{$_.': '.$sig-{$_}."\n"}sort{$sig-{$a}cmp$sig-{$b}}keys%{$sig};
my $VERSION = '0.01'; #'patched' by Jerrad Pierce belg4mit at MIT dot EDU
Re: Perl Apprenticeship Program
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. But don't worry so much about the stigma of shit work -- it's a natural selection thing. Apprentices had better be willing to do some amount of stuff that isn't the most fun thing they could be doing, or nobody will take them on. Masters had better not just dump unwanted junk on their apprentices, or they soon won't have any. Nuke 'em all and let the market sort them out.
Re: Tech documentation (Re: Perl Apprenticeship Program)
Nathan Wiger [EMAIL PROTECTED] wrote: Steve Fink wrote: David Grove wrote: Anyways, that's just one suggestion. Do I have any idea where to find these mythical people? No, unfortunately. Perhaps some feelers on newsgroups might be a good place to start. Personal experience shows that this could be a win, though. Maybe a big "help wanted" sign on perl.org and maybe ora if we can talk them into it. I think I've already volunteered for some of this though, in a roundabout way. Let this circulate for a bit and see what we get from our own insides.
Re: Perl Apprenticeship Program
B. The "master" / "apprentice" relationship is just that - it depends how the people in question relate. As a potential "master" I am all too aware that I am not skilled in teaching - usually because I don't know what is obvious vs what is obscure - so anyone "taught" by me has to ask questions rather than be lectured to. That you both recognize your own limitations and know at least one way how to get around them is a sign that you would be quite an _effective_ teacher, Nick. The adverse can be said for learners. Few know "how" to learn. As an adult with A.D.D., I learned how to learn when I was around 25. In high school I didn't do so well. Well, that's a bit of an understatement. But after I learned how to learn to match my needs, my college tracscript reads solid 4.0. You in particular have a great deal to teach, Nick. I really wouldn't want to see you not try to because you're afraid you might not be a good teacher. Just treat an individual as an individual, and work with him. Things sort themselves out in any kind of relationship like this. p
Re: Tech documentation (Re: Perl Apprenticeship Program)
On Tue, Dec 05, 2000 at 11:28:31AM -0800, Nathan Wiger wrote: Anyways, that's just one suggestion. Do I have any idea where to find these mythical people? No, unfortunately. Perhaps some feelers on newsgroups might be a good place to start. Personal experience shows that this could be a win, though. Open Source Writers Group (http://oswg.org/) is a good starting point. I'm subscribed to their mailing list. I can think of a couple of other good places to try, too, but they're a bit politically incorrect to mention in this context :-/ K.
Re: Perl Apprenticeship Program
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.
