On Wed, 19 May 2010 12:53:05 -0700, Darren New wrote:

> 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.

That's a good point, I've actually used the PHP docs and hadn't thought 
about it.

>>> 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!""

Yeah, that's the sort of thing I've gotten used to seeing.  It's sad...

>> 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.

That's useful.  (not)

Jim

Post a reply to this message