scott <sco### [at] scottcom> wrote:
>
> The issue is with
> people who don't have any previous experience, where SDL is their first
> encounter of such concepts. It's sometimes hard for people with vast
> amounts of experience to imagine how those with no experience might
> interpret such documentation.
>

Indeed. (And that describes *me* pretty well.) Of course, this goes to the heart
of a more basic question: What level of programming knowledge/experience is a
new POV-Ray user supposed to be familiar with? I would like to think that it
need'nt be on the level of the developers! But I could be wrong.

The thing that strikes me about the documentation (and has always done so) is
that some sections are VERY clear in their descriptions--practically no
fore-knowledge required--while others seem to be holdovers from the days when
dedicated programmers wrote things only for other dedicated programmers--full of
tech-speak. (I do realize that the documentation has been a large group effort
over time, with some writers being, shall we say, more attuned to teaching
beginners in an engaging and not-overly-technical style.) I admit it needs to be
a fine balance. I guess my overall concept of 'instruction manuals' in general
is that they should teach in a way that makes concepts and details clear from
the get-go. Without *unnecessary* head-scratching.

There's another element to this though (and it isn't directed at any particular
individual--I've seen it many times over the years in various guises.):
Sometimes there seems to be a bit of built-in...resistance...to making
'simplifying' changes to the documentation. At times it even takes the form of
an expressed dislike of "spoon feeding" a POV-Ray user who has questions about a
particular subject (usually with the admonition to simply "RTFM.") I'm not sure
I understand where this attitude comes from; but it has always been a rather
self-defeating one, IMO. If the desire of all of us is to expand the user base
of POV-Ray, it seems to make sense to make the program easy to learn, via
well-thought-out documentation. And the typical user should have input to this
process--if only to make suggestions-- because he or she is the one 'down in the
trenches' working with it all the time.

Plus, it's a great learning tool! Sometimes a bit difficult to learn, though,
and it need'nt be.

Post a reply to this message