No Documentation
What is it with non-commercial programmers/scripters and documentation? This is something I have noticed for years: people who write small scripts or programs that are not self-executing rarely write more than a few lines of vague instructions on how to use them, even if that much. These people apparently feel that telling other people how to use their creations is unnecessary. “Here’s a great script,” they tell you, “which will do all these great things.” But they don’t tell you where to put it, how to modify it, or anything else that’s necessary for using it. Sometimes these people don’t even make clear what their script even does beyond general descriptions.
Are they just yanking our chains, or do people who acquire the skill to script suddenly lose sight of the fact that most people don’t know how to script or use a command line interface, and can’t figure out what the hell they’re supposed to do with these cryptic files? Better not to publish on the Internet claiming you’ve just created something useful, for all the headaches you cause so many people trying to follow up on your promise of a cool product with needed features. I’m not trying to be ungrateful, these people put a lot of work into some good ideas to make a useful product. But if you spend that much time making the script and then bail on the documentation, then what’s the point?
And I’m not talking about full tech support here. I’m talking about sitting down for two friggin’ minutes and writing down the most basic of instructions. If the file is self-executing, and simply works when you double-click it, then fine, minimal documentation is OK (ironically, those programs usually have good documentation), but the stuff that needs to be changed and placed just so–these are the ones the developers seem to completely abandon once they finish coding.
Were this only a sometimes thing, it wouldn’t be so bad–but it seems that it’s the case nine times out of ten. Is it just me, or what?
Why not post the script here and let users add comments?
If I thought that it would lead visitors here to study each script and find a solution and then bring it forth, that’d be swell. I just never thought to presume people would do that. Are you offering to help?
It would be interesting to try it and see what happens.
By the way, “You Know Who” (whomever you are…), you don’t need to key in a fake email address. Neither Email nor URL (or even a name, in fact) is needed for commenting.
By just randomly typing the four left-hand keys on the second row of the keyboard, you’ve actually tripped the spam filter a couple of times.
Just leave it blank.
I know *exactly* what you mean. It’s not you; it’s both of us
I’ve always thought it was due to a couple of things –
1. A lot of the scripts are written by kiddies who are self-impressed with their own technical wizardry and who feel that a) documentation is beneath them, or b) are so arrogant as to think that any user who can’t work it out ‘deserves’ not being able to use it. The internet seems to be overflowing sometimes with these sort of rude, obnoxious youngsters, don’t you think? Just inhabit any IRC channel … this attitude seems to be everywhere.
2. I think the computer profession has way more than its share of ‘idiot savaant’ types (did I spell it right?). People who are great at coding but lacking in other skills. The type who get top marks for programming subjects at university but have primary school abilities in written English. These types just aren’t up to the documentation.
(Thinking about it, this may be due to a) adults who excel at programming, but are deficient in grammar, as stated; and b) the fact that a lot of kids are good at programming – it’s something that kids seem to ‘absorb’ these days – and haven’t learnt the grammar yet!)
3. Simple ‘fun’ – programming is fun, documentation is not. They’re not being paid for it, so they don’t bother doing it, if it’s not fun.
4. Simple programs don’t really NEED documentation … at least not in the eyes of the programmer … it should be obvious.
Over the years I’ve documented more and more as I’ve gone along … but you’ve got to, as the systems get more and more complex, OR as you accumulate a toolset over time.
Brad
By the way … on my first attempt to post I got a simple page back with a single error message, something like:
Error: Comment Pending template required.
I went back and instead of clicking on POST I clicked on PREVIEW and then followed with a POST, trying a different path. That seemed to work … at least I hope the entry is now sitting there waiting for your approval.
Brad
Yeah, actually I know about the bug, and it’s been commented on. I think somewhere in the code there’s a call for a comment-pending template (which I have) but the address is not hooked in yet or something.
There are two workarounds until I get it fixed:
1. Just hit the back button when you see the error and hit “post” again (“preview” is not necessary), and it’ll always work on the second try. Or,
2. Sign up for a Typekey account and use that–it dodges the pending list and gets published right away without moderation.
If you like, I can set up the Typekey account for you and then hand it over, using one of my throwaway email addresses to verify it.
Hey, I actually just fixed it!
Turns out that the comment-pending template *wasn’t* there, just the placeholder was–when I went into the script to check it out, it was blank! So I went over to Movable Type, got the template script, pasted it, then personalized it.
Now comments without Typekey authorization should return the comment-pending message.