 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Thu, 20 May 2010 09:06:27 -0700, Darren New wrote:
> Jim Henderson wrote:
>> Well, in the OSS world, there tends to be a focus on code rather than
>> on documenting it.
>
> Unfortunately, most people don't seem to realize that a *library* with
> no documentation is worse than useless.
Yeah, that's very *very* true.
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> Unfortunately, most people don't seem to realize that a *library* with
>> no documentation is worse than useless.
>
> Yeah, that's very *very* true.
It could be worse; it could have *incorrect* documentation. (!!)
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Orchid XP v8 wrote:
>>> Unfortunately, most people don't seem to realize that a *library* with
>>> no documentation is worse than useless.
>>
>> Yeah, that's very *very* true.
>
> It could be worse; it could have *incorrect* documentation. (!!)
Not really. Usually there's two kinds of incorrect documentation:
1) Documentation that has bugs in it, which is no worse than a library that
has bugs in it.
2) Documentation for the wrong product shipped. Which is pretty much
equivalent to "no documentation" when you discover that's what happened.
Annoying to spend a couple of days trying to figure out how to get something
to work as documented, finally ask on the newsgroups, and be told "We never
documented that. We just shipped the 1.x docs with the 2.x product." Woulda
been nice to know!
--
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Darren New escreveu:
> Jim Henderson wrote:
>> Well, in the OSS world, there tends to be a focus on code rather than
>> on documenting it.
>
> Unfortunately, most people don't seem to realize that a *library* with
> no documentation is worse than useless.
Good libraries should be intuitive and self-evident enough. Bad
libraries shouldn't be used anyway.
--
a game sig: http://tinyurl.com/d3rxz9
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>>>> Unfortunately, most people don't seem to realize that a *library* with
>>>> no documentation is worse than useless.
>>>
>>> Yeah, that's very *very* true.
>>
>> It could be worse; it could have *incorrect* documentation. (!!)
>
> Not really. Usually there's two kinds of incorrect documentation:
>
> 1) Documentation that has bugs in it, which is no worse than a library
> that has bugs in it.
>
> 2) Documentation for the wrong product shipped. Which is pretty much
> equivalent to "no documentation" when you discover that's what happened.
> Annoying to spend a couple of days trying to figure out how to get
> something to work as documented, finally ask on the newsgroups, and be
> told "We never documented that. We just shipped the 1.x docs with the
> 2.x product." Woulda been nice to know!
So you've never come across documentation that says "setting this value
negative uses the smallest supported value", when in fact setting it
negative causes a segfault?
Then again, would that be a documentation bug or a library bug? I guess
the choice is arbitrary...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Stephen wrote:
>
> But I have been thinking about it. ;-)
>
So what are you doing in June? The weather's turning better so we will be
able to smoke outside without the risk of freezing our brass monkeys :-)
John
--
Cogito sum,|| wbu### [at] tznvy pbz (rot'ed) || GPG Key Fingerprint:
ergo sum, || These opinions are mine alone, || 0D9BCF4CF1B71CA2F5F7
cogito || others can find their own || BFBBCBC34EDEAEFCE453
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 21/05/2010 10:30 AM, Doctor John wrote:
> Stephen wrote:
>>
>> But I have been thinking about it. ;-)
>>
> So what are you doing in June? The weather's turning better so we will be
> able to smoke outside without the risk of freezing our brass monkeys :-)
>
The rumour is that I’ll be Oop North until November. But I’ll arrange to
work from home one or two Fridays.
--
Best Regards,
Stephen
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Fri, 21 May 2010 08:54:24 +0100, Invisible wrote:
> So you've never come across documentation that says "setting this value
> negative uses the smallest supported value", when in fact setting it
> negative causes a segfault?
>
> Then again, would that be a documentation bug or a library bug? I guess
> the choice is arbitrary...
That would be a library bug, because the exception handling is broken or
nonexistent.
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Invisible wrote:
> So you've never come across documentation that says "setting this value
> negative uses the smallest supported value", when in fact setting it
> negative causes a segfault?
Sure. That's a bug in the library or documentation. A fact of life.
It's when they say "Pass the name of the video file to play to
PlayVideoFile() and it'll play." And you spend an hour looking for where
that header is defined, then go googling, and find out "Oh, that's for a
different version. This version doesn't play video files at all."
Or like the P2P protocol stack in Apache.
--
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> Unfortunately, most people don't seem to realize that a *library* with
>> no documentation is worse than useless.
>
> Good libraries should be intuitive and self-evident enough. Bad
> libraries shouldn't be used anyway.
Nice in theory, not always possible in practise. Sometimes it's
unavoidable that when a library offers a lot of functionallity, it's not
obvious how to start using it - even if it *is* easy to use once you
know how.
This is why documentation is necessary.
(Also, I don't care how intuitive a library is, there are usually
edge-cases where it's not obvious what the library will do. Usually you
need to know about these.)
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
