Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?

Documentation for non-Geeks

by skazat (Chaplain)
on Jun 23, 2008 at 03:56 UTC ( #693432=perlquestion: print w/replies, xml ) Need Help??

skazat has asked for the wisdom of the Perl Monks concerning the following question:

This is less a technical question and more of cultural question:

My bread-n-butter web app is seeing a lot my attention lately, mostly because a very large hosting company has it as a one-click installation option for it.

This means the barrier to entry to use the program has dropped significantly, but now, when people want to do more with it, the find the barrier exceeds what they know and they feel, not so good.

What words of wisdom should I pass on to these people who want to say, configure a plugin to the program, but configuring a plugin means editing configuration variables on top of script and uncommenting lines. This isn't rocket science, but it's Murphy's Law that if you can mess it up, my Fine Users will.

At least in this release cycle, I can't make this any easier, but I was hoping that, perhaps there's a resource available entitled something like, "Mucking about in a Perl program, if you're not a perl programmer (or a programmer at all!)"

I've personally have been grappling with two types of instructions - one type attempts to go through the steps, as if the person wants to know what they are doing, the other type of instruction just says, "DO THIS" and things will work out. I'm thinking the latter is the way to go, as my Fine Users rather don't care about the former (I'm the one that cares about the former)

Is this something people can empathize, or is it the opinion that if they can't, they won't, and they probably should not. As I said, configuration is uncommenting lines and filling in variables. THis isn't something with a Makefile. Asking my users to make, make test and make install is like asking where the restroom is in the French Provence.

Thanks for any leads.

Replies are listed 'Best First'.
Re: Documentation for non-Geeks
by marcussen (Pilgrim) on Jun 23, 2008 at 04:16 UTC

    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
    Having said that, many people struggle with Apache despite it's relatively good documentation

    Confucius says kill mosquito unless cannon

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

        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 '' is okay, but "" 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 ...
        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
Re: Documentation for non-Geeks
by Anonymous Monk on Jun 23, 2008 at 06:53 UTC
    Eval config bad, eval in the hands of non-trained lethal, its best you abandon eval ASAP
Re: Documentation for non-Geeks
by hangon (Deacon) on Jun 23, 2008 at 18:17 UTC

    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,

Re: Documentation for non-Geeks
by Anonymous Monk on Jun 23, 2008 at 06:51 UTC
    I say you complain to the company :) or charge them for a granny friendly configurator :D
      I *am* the company
Re: Documentation for non-Geeks
by DrHyde (Prior) on Jun 26, 2008 at 09:57 UTC
    I don't understand "Asking my users to make, make test and make install is like asking where the restroom is in the French Provence.". Are you saying that getting your users to make / make test / make install is easy?

Log In?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlquestion [id://693432]
Approved by GrandFather
Front-paged by Arunbear
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others perusing the Monastery: (5)
As of 2022-05-23 15:03 GMT
Find Nodes?
    Voting Booth?
    Do you prefer to work remotely?

    Results (82 votes). Check out past polls.