On Tue, 21 Sep 1999 01:25:55 -0700, Ken wrote:
>  When a new patch comes out however the writer of the patch is inundated
>with questions from the users of the patch seeking clarification on
>operating parameters and ideologies behind the function of the patch.
>One would think that the patch writers would try to head off all of the
>questions they are eventually going to have to field anyway by spending a
>few minutes documenting their new labor of love. 

I think part of it is psychological.  When we're writing documentation, 
we're not writing for anyone in particular, and it's easy to think that
nobody will ever actually read it.  When we're answering questions in the
newsgroups or by email, there's actually a specific recipient - someone 
who will definitely read the response - so it doesn't feel so much like
wasted effort.

Also, there's the fact that when we're answering a specific question, it's
probably only about a single facet of the whole thing, so it's a much less
overwhelming task than documenting the whole thing at one go.  This is 
especially true of complex patches with no well-defined purpose, like UVpov 
or the isosurface patch, or of huge patches like the Superpatch (which I've
opted to "document" by including the original docs for each patch, sparse 
though they may be.)

Post a reply to this message

Ron Parker wrote:
> 
> On Tue, 21 Sep 1999 01:25:55 -0700, Ken wrote:
> >  When a new patch comes out however the writer of the patch is inundated
> >with questions from the users of the patch seeking clarification on
> >operating parameters and ideologies behind the function of the patch.
> >One would think that the patch writers would try to head off all of the
> >questions they are eventually going to have to field anyway by spending a
> >few minutes documenting their new labor of love.
> 
> I think part of it is psychological.  When we're writing documentation,
> we're not writing for anyone in particular, and it's easy to think that
> nobody will ever actually read it.

A poor asumption I can assure you :)

>  When we're answering questions in the
> newsgroups or by email, there's actually a specific recipient - someone
> who will definitely read the response - so it doesn't feel so much like
> wasted effort.

Immediate gratification not withstanding documentation efforts are seldom
wasted time.

> Also, there's the fact that when we're answering a specific question, it's
> probably only about a single facet of the whole thing, so it's a much less
> overwhelming task than documenting the whole thing at one go.  This is
> especially true of complex patches with no well-defined purpose, like UVpov
> or the isosurface patch, or of huge patches like the Superpatch (which I've
> opted to "document" by including the original docs for each patch, sparse
> though they may be.)

  As an engineer I have had the task of working on several documentation
projects. I agree that it can be a daunting task and if you want a real
good time try to do it sometime for a mil spec application -- OUCH !
For other types of documentation like for POV-Ray patches I would think
it would almost be fun in comparison. Oh well as you say human nature is
a beast and we are all guilty at not fulfilling our obligations from
time to time.
 Is a lack of documentation grounds for erroneous bug reports due to lack
of understanding on the part of the user ? Look at the posting history in
the bug reports group... :)

-- 
Ken Tyler

See my 1000+ Povray and 3D Rendering and Raytracing Links at:
http://home.pacbell.net/tylereng/index.html

Post a reply to this message

By the way, if you really want to have all sorts of info about the photon
mapping in UVPov, download the PostScript file linked from
http://nathan.kopp.com/photons.htm.  That PS file is the paper that I wrote
for my directed study, and it probably contains more info than you want or
need.  It lacks tips and tricks, because I did not know of many tips or
tricks when I wrote the paper.

-Nathan

Post a reply to this message

On Tue, 21 Sep 1999 23:32:53 -0400, "Nathan Kopp" <Nat### [at] Koppcom> wrote:

>By the way, if you really want to have all sorts of info about the photon
>mapping in UVPov, download the PostScript file linked from
>http://nathan.kopp.com/photons.htm.

  Nathan, by any chance would you happen to have this document in another
form such as plain text or Adobe Acrobat or HTML? I don't have anything to
read a Postscript file with. However, don't go through the hassle of
converting it or anything like that - I'm just curious.

-- 
Alan ---------------------------------------------------------------
http://www.povray.org - Home of the Persistence of Vision Ray Tracer
news.povray.org - where POV-Ray enthusiasts around the world can get
together to exchange ideas, information, and experiences with others

Post a reply to this message

Ditto.

-- 
Ken Tyler

See my 1000+ Povray and 3D Rendering and Raytracing Links at:
http://home.pacbell.net/tylereng/index.html

Post a reply to this message

Alan Kong <ako### [at] pacbellNO-SPAMnet> writes:

> On Tue, 21 Sep 1999 23:32:53 -0400, "Nathan Kopp" <Nat### [at] Koppcom> wrote:
> 
> >By the way, if you really want to have all sorts of info about the photon
> >mapping in UVPov, download the PostScript file linked from
> >http://nathan.kopp.com/photons.htm.
> 
>   Nathan, by any chance would you happen to have this document in another
> form such as plain text or Adobe Acrobat or HTML? I don't have anything to
> read a Postscript file with. However, don't go through the hassle of
> converting it or anything like that - I'm just curious.

You should really get a version of "ghostscript" and "ghostview". The 
former is a free Postscript-Interpreter, the latter a viewer that uses
it. They are available for a lot of OSes (e.g. Windows, OS/2, Linux,
Solaris,...). Furthermore, ghostscript can be used to print the documents
on a variety of printers.

Both programs should be available on your favorite ftp server.

Thomas

-- 
http://www.fmi.uni-konstanz.de/~willhalm

Post a reply to this message

Thomas Willhalm wrote:

> You should really get a version of "ghostscript" and "ghostview". The
> former is a free Postscript-Interpreter, the latter a viewer that uses
> it. They are available for a lot of OSes (e.g. Windows, OS/2, Linux,
> Solaris,...). Furthermore, ghostscript can be used to print the documents
> on a variety of printers.
> 
> Both programs should be available on your favorite ftp server.
> 
> Thomas

??
http://www.cs.wisc.edu/~ghost/

-- 
Ken Tyler

See my 1000+ Povray and 3D Rendering and Raytracing Links at:
http://home.pacbell.net/tylereng/index.html

Post a reply to this message

I chose PS format for cost & portability.  While Acrobat viewer is free, the
creator is not.  The paper was written in Wordperfect, and the "save as
HTML" feature is far from perfect.  And, as mentioned, PS viewers are
available, and PS creators are as easy to come by as your favorite PS
printer driver.  If enought people request HTML, I'll put together an HTML
version, though.

-Nathan

Alan Kong <ako### [at] pacbellNO-SPAMnet> wrote
> On Tue, 21 Sep 1999 23:32:53 -0400, "Nathan Kopp" <Nat### [at] Koppcom> wrote:
>
> >By the way, if you really want to have all sorts of info about the photon
> >mapping in UVPov, download the PostScript file linked from
> >http://nathan.kopp.com/photons.htm.
>
>   Nathan, by any chance would you happen to have this document in another
> form such as plain text or Adobe Acrobat or HTML? I don't have anything to
> read a Postscript file with. However, don't go through the hassle of
> converting it or anything like that - I'm just curious.
>

Post a reply to this message

On Thu, 23 Sep 1999 19:48:42 -0400, Nathan Kopp <Nat### [at] Koppcom> wrote:
>
>I chose PS format for cost & portability.  While Acrobat viewer is free, the
>creator is not. 

GhostScript for Unix comes with a free ps2pdf utility.  It's not perfect, but 
if you used normal PostScript fonts it'll work pretty well.

Post a reply to this message

On 23 Sep 1999 10:08:36 +0200, Thomas Willhalm
<Tho### [at] uni-konstanzde> wrote:

>You should really get a version of "ghostscript" and "ghostview".

  I will try this, thanks.

-- 
Alan
http://www.povray.org - Home of the Persistence of Vision Ray Tracer

Post a reply to this message