Fri, 18 Oct 2013

When context is key ...

Here's an amusing case of how not having a certain piece of knowledge (if knowledge comes in pieces) can make you totally miss the boat.

I was trying to get the web server Nginx running with cgi (Ode is a cgi script. nginx doesn't handle cgi's the same way as the Apache server but requires that they be launched via a seperate cgi process handler). Lots of things are different than my previous experience with Apache and a different Linux distribution: the default document root, the configuration file syntax, etc. But I was calmly troubleshooting one step at a time, trying to think and to remember all the usual gotcha's (like file permissions). I knew it would take a bit of work, and I wanted to understand how Nginx worked so I took it slowly.

I was using the 'fcgiwrap' program which I installed via my distribution's package manager to run ode as a cgi, making it available to nginx. This, too, was new, but I seemed to be making headway: what I learned from the first time I installed Ode was that error messages are a good thing because at least you know there's something running to send an error message back, and I saw that nginx was getting an error back from the cgi wrapper program. So, I stayed calm.

But it was starting to take a bit long ... until I finally realized what my problem was. A complete misunderstanding of how these fastcgi programs work.

Let's see if I can avoid the same pitfall I will describe in a minute when I get to the moral of this story. Essentially: where I thought I needed to launch the cgi script (ode.cgi), I actually needed to launch the cgi wrapper, and tell nginx to tell the wrapper what cgi script to run. Does that make sense? probably not (I'm thinking of people with little to no previous knowledge of these kinds of things).

Well, I'm tired out from an hour of troubleshooting so I won't explain in more detail. But how did I finally get this? by reading the documentation of a different program than the one I thought I needed to be understanding, where I saw a configuration example which clued me in. The whole time I was thinking 'fastcgi' worked one way, when really they worked differently and thus I was reversing two pieces of the puzzle.

The moral of the story? Is not that I, as the learner, need to learn to learn better. What else can I do? Eventually I noticed what the issue was, but I don't think I had much control over how long that took. The moral of the story is, rather, that documentation can be wonderful and complete, but still always assumes a certain level of background information and it can be really difficult to imagine the framework from which someone else will read your documentation.

(Incidentally I was talking about this, the level of detail to put into instructions/tutorials, with some the other day. I tend to try to back way up and give lots and lots of context. I think that can be helpful, but it sure takes a lot of energy and time -- so much that I often end up aborting the documentation effort).