clipka <ano### [at] anonymousorg> wrote:


> Technically, that would not be an explanation, but an example.

I want my POV-Ray lawyer.


> You're right in that the docs on POV-Ray's UV mapping implementation
> apparently presume the user is already familiar with the concept of UV
> mapping.
> For a person familiar with the concept, I think it is pretty
> self-evident what `uv_vectors` does.

I'm not really sure what the point of that is.
You may as well have a "dataless" document.
The people who don't know what the data means won't understand it, and the ones
who already understand it don't need to see it.

It seems like some strange "documentation for the sake of documentation" rather
than what I'd expect all of that work that went into preparing it to be for -
being a manual for the user.  There's a whole cubic mapping diagram to show how
a texture wraps around a cube.  An additional sentence or two - as explanation,
or example - either, or, or both - would likely suffice.

> Note that you're looking at the reference section, not a tutorial. I
> think it is legitimate to expect the reference section's reader to be
> already familiar with common 3D graphics concepts; UV mapping is one of
> those.

I think this is setting up a false dichotomy.
Either all you need is a blurb that you're already expected to understand - or
you need a full-color 10-page tutorial.

I think there's quite a lot of POV-Ray users - be they the "target audience" or
not - that often point out that the documentation falls just shy of dispelling
the confusion they have about a topic.
You can call them "complaints" - but I believe they are observations offered as
suggestions and solutions, and improvements.

>
> Of yourse you may rightly claim that adding an in-depth explanation of
> UV mapping, with examples and all, to the _tutorial_ would do the docs
> some good. I wouldn't argue with that; currently all we have is a
> section on UV mapping in mesh2.

Certainly a tutorial would be nice, as would something that touches on
UV-unwrapping, but I think that a few extra lines in the reference section would
be the easiest and most likely to be completed first step.


> "I failed to understand this documentation, so I turn to complaining
> about the documentation" - also a not too uncommon and not too helpful
> schtick.

Characterize it however you'd like.
It's an open-source free software package offered to the public, and one would
hope that this is a forum where open an honest discussion is encouraged.
I've voiced my observations, concerns, and suggestions for making the learning
curve a little easier to climb.

> There is certainly a point to it when the person is an average member of
> the target audience, because it may be an indication that the
> documentation is indeed missing its audience. Hoever,
>
> (a) that point is moot if the person isn't a member of the target
> audience in the first place (because the document in question presumes
> certain background knowledge) or is the only person who happens to not
> get this part of the documentation, and

Take a poll.

> (b) if what you really want is an explanation (as opposed to a
> discussion about whether the docs are good or not), don't complain about
> the docs; rather, ASK FOR AN EXPLANATION.

Yes, I could, but I also see documentation as a way to preemptively address
topics that are likely to need clarification, so that people don;t have to open
the docs, search the docs, read the docs, and then search the forums, and sift
through all of the posts that may or may not eventually answer the question they
have.   Which usually leads to the same questions being asked again and again,
rehashed, and then all of this might be repeated if something fundamental is
altered in a version change.

So I point out that the documentation doesn't seem to quite answer my question,
and the alert forum reader would surely, as an average member of my target
audience who is already familiar with common 3D graphics, and the software
package in particular, would be expected to understand that that I AM asking for
an explanation.

:P

I mean, I do try to do as much researching of a topic as I'm able to, before I
ask, and then I give it a go, and give thanks and credit.

But I don't believe I'm off-base.
http://news.povray.org/povray.advanced-users/message/%3Cweb.5b600737497a6101a47873e10%40news.povray.org%3E/#%3Cweb.5b60
0737497a6101a47873e10%40news.povray.org%3E

#GoKennethTheDestroyer

Kenneth.  I want Kenneth as my POV-Ray lawyer.

Post a reply to this message