You might find it more worth while to move configuration to a file. You can then additionally proceed to create a friendly (web?) interface to modify the values. The script can then write out the new configuration to a file on the server or a file the user can download and upload to the server in their usual manner. Even with documentation someone will ignore/misinterpret the documentation and break things anyway.

Assuming that your average user is smarter than a stick of butter I would go for the type of inline documentation used by Apache and similar programs where they place comments and examples above the actual line, things like;
To enable <feature> uncomment the line below
# BREAD_AND_BUTTER = 1
Having said that, many people struggle with Apache despite it's relatively good documentation

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
[download]

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

 

$WIDGET = B<hump>;
[download]

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

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.

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 ...
[download]

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::").

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

Ah! I forgot to mention, I do like the idea of the outside config file and the web interface to it. Right now, I'm stuck with the outside config file written in Perl (just perl vars, arrays, hashes). I'm a little concerned that there's going to be some hidden problems, say, evaling the variables into their own namespace and then presenting the values to be changed in an intelligent way to the user. I don't know what yet, but it seems to me, that if I got this direction, I use something other than Perl to write the Config file in. I think there's even CPAN modules that'll read/write/edit their own Config file representations. Next major release cycle ;)

If you're willing to change the configuration format a bit, AppConfig is very good for letting you create configuration files that don't look like perl.

Though if you want a program to read & write the configuration, XML::Simple is at least 1 good choice

---

just another cpan module author

Thanks.

This is a question I've struggled with too. For the long run I think your best solution is to bite the bullet and provide a nice web based configuration. Until that time you obviously have more limited options. I have no idea what to do with the people who cannot get it through their head that a Word document is not a plain text file, but for the rest perhaps just providing a lot of examples would help. It's often a lot easier to grasp a concept when you see it rather than just reading about it,

I *am* the company