http://qs321.pair.com?node_id=693446


in reply to Re: Documentation for non-Geeks
in thread Documentation for non-Geeks

These are fine ideas, and I like them quite a bit.

Currently, there is an option to use a config file - it's just a file of Perl that's then eval() in. In the future, I don't think I want to use straight Perl.

I also say that it's an option since there's also a ProgramName::Config module, that holds all the default global configurations. What's funny, is that people do edit this directly - having them make a config file is a little beyond them - even when I give an example of one, and even, if you can believe me, have the program automatically make them one, on behalf of them, so I give two sets of directions - one that says "do edit the ProgramName::Config" file and one that says don't. Sigh.

Anyways, the people who don't, go through the ProgramName::Config file and they come to inline documentation, written in pod, something like this:

=pod =head1 $WIDGET To turn Program into a Camel, Set, C<$WIDGET> to, B<hump>: $WIDGET = 'hump'; =cut $WIDGET = 'no hump'; =cut

I will get people who will turn the variable part to this:

$WIDGET = B<hump>;

And then not understand what they did wrong. Or they'll see the example in the pod and say, "Well, it's already set to, "hump". These are the type of problems I'm having :)

It may behoove me to just simple make a doc up about editing perl files for the uninitiated, it's just has to be very smart about how you're to word these things.

I know these aren't huge problems when $Geek talks to other $Geek, no matter what $Geek->type returns. These are problems that happen when $Geek interfaces with, say, a receptionist, or a beginning website designer, or just someone that bakes cookies, in a small town, that needs the program you've created. It's almost an old world vs. new world problem. And in that case, it's time to listen to the Modern Lovers ;)