Am 20.05.2011 03:56, 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're surprised, you ask, you learn, you document what you learned so 
that others don't need to ask again. That's how it /could/ work.

The dev team is not constantly skimming through the docs with the eyes 
of a new user (how could they!) searching for stuff that's poorly 
documented.

Nor does the dev team have an abundance of energy to work on the docs. 
Jim is doing a great work on that, but he has a life, too. Essentially 
we need people who not only /find/ flaws in the docs, but also /fix/ them.

Another thing that should be noted is that the dev team has changed a 
lot over the lifetime of POV-Ray so far; some members left, others went, 
and various people outside the official dev team contributed code and/or 
documentation. There are things in both the docs and the code the 
current dev team does /not/ know by heart.

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

That may well be. Software authors who know how their software works 
tend to take some things for granted that new users possibly won't. 
They're also prone to language that a fellow programmer might 
understand, but an artistically oriented user may possibly not.

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

... and I bet you've always supplied a correct, error-free, complete and 
end-user-friendly documentation, huh?

If you did, then congrats - you might be the type of person we could 
need help from.

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

Well, the source code is there to have a look at, too (and even toy 
around with). It's the most precise documentation we cold ever ask for. 
(Unfortunately it's not very end-user-palatable.)

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

You know, I have my own approach at things that frustrate me.

A while ago it frustrated me as a POV-Ray end user that while POV-Ray 
3.7 beta (I think it was beta 28 or 29) could make use of multiple 
cores, it couldn't do so for radiosity.

Knowing that the dev team was pretty busy, I decided to give it a try 
and invest some of my /own/ energy into /making/ it use multiple cores 
for radiosity.

I did. Previously I had only vague ideas of how POV-Ray worked at its 
core, how radiosity worked, and so forth. I invested the energy to 
/learn/ how it worked, in order to fix what was frustrating me. Yes, I 
did my own share of ranting over the existing radiosity code as I dug 
deeper into it - but at the same time I busied myself fixing it.

So pointing out flaws is one thing - ranting about them without adding 
anything more helpful is a different thing.

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

Believe me - we /want/ the documentation improved. We just don't have 
the energy ourselves at present. There's other things that have priority 
(for us as a dev team) over fixing stuff in the docs that hasn't changed 
at all from 3.6 to 3.7.

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

I'm not doing it myself because I'm poor at writing end-user docs; being 
pedantic as I am, I find it difficult to find a proper balance between 
precision and legibility, so it costs me a lot of energy to do such doc 
changes. I have a much easier time explaining things to individual 
people than to a broad anonymous audience. And if we'd be talking about 
a technical specification, where precision is all that matters, I'd have 
a much easier time.

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

So Thorsten's advice was "incorrect" because he simply wrote "just add 
all_intersections" rather than "just add all_intersections where it fits 
according to the documented isosurface syntax"? Great. I prefer to disagree.

Post a reply to this message