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 ;)

Replies are listed 'Best First'.
Re^3: Documentation for non-Geeks
by gloryhack (Deacon) on Jun 23, 2008 at 07:52 UTC
    I highly recommend something like (but not necessarily) Config::IniFiles so that those users who care to muck about in the guts of the thing (the configuration thing, not the code thing) can, and any web interface you might create will be able to work with it and not screw things up. This keeps the users completely out of the code but gives them a very high degree of control.

    Asking users to edit code is just begging for trouble. You cannot expect the end user to know that 'user@example.com' is okay, but "user@example.com" is not, or that $things and @things are two different things. It's much easier for you to use a non-eval'd configuration file, and much less scary for the end user, too.

Re^3: Documentation for non-Geeks
by jethro (Monsignor) on Jun 23, 2008 at 14:20 UTC
    You might plaster your ProgramName::Config file (and maybe other prominent script files too) with comments in big letters every 20 lines:
    # DO NOT EDIT THIS FILE. To change the configuration do this: # Call this and do that # You now can edit the configuration in file ...
    Obviously your users are intelligent enough to find this file, but rather forgetful about infos they get with the program but need weeks later. Don't tell them to edit ProgramName::Config. Instead make sure they see the information on how to configure when they want to configure

    Don't ever give the impression it is ok to edit the code. NEVER EVER. Instead provide them with an easy path to success and make sure they find out about that path by putting it in all the places they will look at at that time

    There are CPAN modules to read in config files. You will find some of them if you search for modules in the "Config" tree (i.e. that begin with "Config::").

Re^3: Documentation for non-Geeks
by TGI (Parson) on Jun 23, 2008 at 16:35 UTC

    When you pick your config file format, think about how it will be used. Will users be editing the file in a text editor (likely Notepad-yech)? Or will they be using your web interface? The answer to these questions will determine how important it is that the format is easy to edit.

    For example, some of my apps use YAML for configuration and others use Config::IniFiles. YAML is great because I can easily serialize an arbitrary data structure, but complex files are too easy to mess up if edited by hand. INI require more work to store complex structures, but they are far easier to edit by hand.

    A couple of extra pointers: Remember to validate all of your configuration variables. Provide a way to create a blank/default template configuration--a newb may hopelessly mangle his configuration while editing it. If he can easily make a clean copy he will be much happier when this happens (I've been on both sides of this situation :) ).

    There are plenty of great Config modules on CPAN--take a look.


    TGI says moo