"clipka" <ano### [at] anonymousorg> wrote in message 
news:4dd541fb@news.povray.org...
> Am 19.05.2011 05:06, schrieb SGeier:
>
> If you think the documentation is bad, then you're happily invited to help 
> make it better.

I am honestly not being facetious when I (honestly, serious!) ask: How is 
that supposed to work, when I don't know how POV-Ray works? I look into the 
documentation when something doesn't work as I expect. I learn something, 
try something, and realize it doesn't work as written in the docs either. 
How on earth am I supposed to now suddenly write better docs?

I've been poking my head into POV-Ray for several years now - I d/l the 
current version, I tinker with it, I give up. Because every time I run into 
the same kinds of problems that aren't documented and when I ask about them 
nobody takes the time to examine what was communicated how in the docs and 
when I complain about the docs I'm being told that I'm free to make them 
better. But how should I do that, when I don't even understand some very 
basic, simple things about POV-Ray *because they're not documented*?

You really think those who don't know how POV-Ray works wil create better 
documentation than those who do know it?

> It's not like the developers & other people helping with POV-Ray would be 
> paid anything for it; our only payment is the joy of doing it (and every 
> programmer knows that implementation work is more fun than writing 
> documentation), the joy of seeing people get good results of it, and the 
> joy of receiving some motivating feedback from the community now and then.

I've been writing (and giving away) code since the eighties, I understand 
that joy. But I also understand that the chance of "seeing people get good 
results of it, and the joy of receiving some motivating feedback from the 
community" increases when people actually have chance to use my creations --  
which requires clear, unambiguous documentation. In which someone can find 
what they're looking for.

Otherwise you've created a magic binary that people *cannot* get good 
results from.

I understand well, that in the end you're just hurting yourself by not 
taking the opportunity to take every post to these ng as an opportunity to 
ask "how should we have written the answer to this in the docs and where did 
you look for it". But exactly *because* I've written my share of software, 
it frustrates me to no end that there's something here that seems pretty 
solid enough and appears to be getting better every time I look -- but it 
will never be something I use in any serious way, because nobody who knows 
the inner workings can be bothered to write down what is actually going on 
in this piece of code.

> No. To the programmer, the /intention/ is the end-all and be-all. If the 
> code fails to match that, it is buggy. If the documentation fails to match 
> that, it is either wrong (making an explicit statement that is not true), 
> incomplete (failing to make an explicit statement that is true bot not 
> necessarily obvious to the user), or imprecise (making a statement that 
> can be interpreted in a way that is true, but also in another way that is 
> not).

It's all fine that you have all these fine levels of gradation in which 
documentation fails. To the end-user, however, they make no difference: As 
Feynman said "if it disagrees with experiment, it's wrong".

But OK: so the documentation is "incomplete". Yet nobody is changing it. 
Instead *I* have been asked to improve on it - even though I have no idea of 
the very things that made me post here in the first place. It would be great 
if every post to these ng was taken as an opportunity to improve your 
stuff -- but if you don't want to do that, then why bother in the first 
place? Why even have these ng?

Once you posted the order in which the intersection test and clipping 
happen, that side of POV-Ray's behaviour was clear to me. So why haven't you 
put that explanation into the docs yet? Yes, I could try to do it myself, 
but I'd only mess it up in some subtle way since I only heard of it the 
first time yesterday (or whenever I read your reply).

> BTW, to the end user, the /expectation/ is the end-all and be-all; the 
> documentation can only serve to modify those expectations. So if some docs 
> do not explicitly mention the program's behaviour in a very rare 
> situation, who is outright /wrong/: The documentation, or the user's 
> expectations? I dare say the latter, because the docs simply cannot 
> foresee all that a user may expect.
>
> Also note that in real life there is no such thing as a /complete/ 
> documentation.

Actually, there is: the program as shipped is the final documentation. If 
you aren't sure about something, feed it to the program and see what 
happens. Whatever that is, that's how this program works.

Much of that can be predicted if you know the source, some details may hinge 
on details in some library or the compiler or OS. If someone says "just add 
all_intersections" and I add all_intersections and the result is a 
parse-error, then the advice was wrong. You may niggle over "incomplete" or 
"imprecise" or whatever, but when everything is said and done, following the 
advice to the dot leads to a parse error. *correct* advice solves my 
problem. *good* advice is like much of what you've been doing: pointing out 
what's wrong and where and how.

[...]
>> If that is "as intended", then this intention needs to be communicated 
>> (in
>> the docs, not here).
>
> (4) There is no /need/ to communicate the programmers' intentions to the 
> users. It's probably /helpful/, but there is no such /obligation/ to the 
> dev team - neither legally (see the license) nor morally (what you get 
> from the dev team is a free gift, and you can either take it or leave it, 
> and there's nothing you can /demand/ on top).

The concept of "need" is always tied to a purpose of some sort: in order to 
achieve X you *need* to Y.

If, to the programmers, the intent is the end-all be-all (as you claimed, 
and as I'm happy agreeing with) and if the programmers hope that people will 
get good use out of their producs (as you maintain and as I have no quarrels 
agreeing with) then they *need* to document their intent.

You are the only one here construing any kind of legal or moral dimension to 
the term "need".

Post a reply to this message