Thorsten Froehlich wrote:
>In article <qa159vss0903hu8oms990f7nees385mv0q[at]4ax.com> , ABX
><abx### [at] abxartpl>  wrote:
>
>> Perhaps this should be extended about binary nature of this
>> file and portability limitations.
>
>No, because that is not of concern of, nor understandable by, users.  There
>is such a thing as "too much" documentation for users.  Keep in mind this
>document isn't a software engineering style document, but a simple user
>manual.  Users are not be able able to understand what is behind it because
>they cannot know the technical background.  Thus, it doesn't belong into a
>user manual.
>
>    Thorsten

Then maybe there need to be two manuals.  One for regular users, and one for
power users.  The first one could be a stripped down version of the current
documentation, since it already has several topics that are covered in
graphic mathematical detail.

The second one could be a beefed up version of the current documentation,
for those who are curious about how the innards work, without having to
resort to the most in-depth documentation, i.e. the source code.  I find
myself venturing into the code to see how things work that should be
documented, such as how POV-Ray handles refraction between multiple objects
(such as water in a glass bottle; see my thread a couple posts before this
one).

In fact, my latter example (refraction) is not some esoteric quirk that no
one will ever use.  It is a very commonly used feature that, in my opinion,
was implemented incorrectly.  Had there been better documentation, perhaps
the design team would have found the flaw earlier (nothing points out a
mistake like trying to document how something works), or someone else would
have come forward with a fix earlier.

Post a reply to this message