Jim Henderson wrote:
> Yeah, that's a trend that's been around for a while, but I can't say I've 
> ever seen it used effectively.  

The PHP docs are pretty good at it. But that's because the docs themselves 
really tend to answer your questions. They tend to have a decription, what 
the parameters mean, sample code, etc. They don't just say "The flooble(zop) 
function floobles the provided zop."

The commentary generally had either significant clarifications or sample 
code for how to combine different features to get what you want, etc.

>> What's the point of buying proprietary software if you have to document
>> it yourself, or experiment with it to figure out how it works even in
>> normal cases?  Sheesh.
> 
> That's a pet peeve of mine today (just software documentation in general 
> not being very high quality - I remember telling someone about a doc page 
> that described a product UI by pointing out things like "the username 
> field is where you enter your username" and "the login button is what you 
> press to login".

"To insert a column, use the Insert Column menu. But if you needed me to 
tell you this, return the software to the store."

"How do you like my documentation so far?"
"I'm only up to the chapter entitled "Duh!""

> Duh, smack me with a 25-story building, I never woulda' guessed that. >:-(

Some of the Microsoft API libraries are starting to have rather sparse 
documentation. They have things like "Components.Add(aComponent) adds the 
component to the components list."  They don't mention "Oh, and by the way, 
if the enclosing object has already been initialized, then this will invoke 
Initialize() on your component automatically. If the enclosing object hasn't 
been initialized, this will invoke Initialize() after the enclosing object 
invokes Initialize() but before that invokation returns."

You don't want to initialize things twice, but you also don't get told 
if/where it is the system does it for you.

-- 
Darren New, San Diego CA, USA (PST)
    Ada - the programming language trying to avoid
    you literally shooting yourself in the foot.

Post a reply to this message