|
![](/i/fill.gif) |
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
|
![](/i/fill.gif) |