 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Why do patch writers document their patches so poorly when the bother
documenting them at all ?
--
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Sun, 19 Sep 1999 22:22:02 -0700, Ken wrote:
>
>
> Why do patch writers document their patches so poorly when the bother
>documenting them at all ?
Because we don't like writing documentation. Actually, I agree with you.
I know the superpatch documentation is really horrible, but it's that way
because I mainly cut-n-pasted the docs from the original patches, editing
only for a consistent style and not for content. Looking back on it, the
isosurface stuff is documented really terribly; it's practically painful
to look at.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
> Why do patch writers document their patches so poorly when the bother
> documenting them at all ?
The program knows what to do. :)
With the one I just released, I was up all night putting it together and
had to make a new splash screen and all that other stuff then put the
files together and when it came time to write the docs, I was pretty
spent. I was also nervous about telling people what to try because I
wasn't sure if everything was working. Heh heh.
-Mike
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Mon, 20 Sep 1999 10:25:36 -0500, Mike wrote:
>> Why do patch writers document their patches so poorly when the bother
>> documenting them at all ?
>
>The program knows what to do. :)
>
>With the one I just released, I was up all night putting it together and
>had to make a new splash screen and all that other stuff then put the
>files together and when it came time to write the docs, I was pretty
>spent. I was also nervous about telling people what to try because I
>wasn't sure if everything was working. Heh heh.
That's my take, too. I end up having something I could ship, if I had
documentation, but I don't feel like doing the docs and I end up putting
them off for weeks. On the other hand, I don't feel right about releasing
undocumented software.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Ron Parker:
>On the other hand, I don't feel right about releasing
>undocumented software.
The newer features obviously don't have tutorial websites because
people are still learning what to do with them, but why not include
links for the subjects that are covered as they become available.
--
Phil
...coffee?...yes please! extra sugar,extra cream...Thank you.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
They don't want to deprive us of the joy of discovery?
Margus
Ken wrote:
>
> Why do patch writers document their patches so poorly when the bother
> documenting them at all ?
>
> --
> 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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Phil Clute wrote:
> The newer features obviously don't have tutorial websites because
> people are still learning what to do with them, but why not include
> links for the subjects that are covered as they become available.
>
> --
> Phil
Well i try to give Ron as much docs as I can and I am starting a
tutorial
section for Superpatch at my site http://www.xenoarch.com/tutorials
--
Matthew Corey Brown XenoArch
mcb### [at] xenoarch com http://www.xenoarch.com
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Ron hit the nail on the head. We don't like to document. Coding is much
more fun. :-) My best documentation came from replies to people's
questions. I've included replies in portions of the UVPov documentation on
a variety of occasions.
-Nathan
Ken <tyl### [at] pacbellnet> wrote
>
> Why do patch writers document their patches so poorly when the bother
> documenting them at all ?
>
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
That's what you guys ought to do: write a simple explanation of what that
new doohikey you added does, have someone bust their brains out figuring out
its pros and cons and tricks, and then have that person send you a
documented explanation. It's just that simple! =)
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
TonyB wrote:
>
> That's what you guys ought to do: write a simple explanation of what that
> new doohikey you added does, have someone bust their brains out figuring out
> its pros and cons and tricks, and then have that person send you a
> documented explanation. It's just that simple! =)
Amusing.
When someone is new to the official version of POV-Ray there is a
certain amount of justification to simply beat them over the head with
RTFM !!! Why is that justifiable ? Because the program is so well
documented and dozens of examples are given to explain the concepts.
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. If you add up the number
of sentences written in reply to user questions you would see there is
no time lost by taking the time to write a little about what the patch is
supposed to do and how it works. Who better to document it that new patch
than the person who seemingly knows how it works the most - the patch's
author. We the unsuspecting users of the patch are not mind readers you
know !
--
Ken Tyler
See my 1000+ Povray, 3D Rendering, and Raytracing Links at:
http://home.pacbell.net/tylereng/index.html
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Thu, 23 Sep 1999 01:12:01 -0700, Ken <tyl### [at] pacbellnet> wrote:
>http://www.cs.wisc.edu/~ghost/
I'll check this out, Ken. Thanks.
--
Alan
http://www.povray.org - Home of the Persistence of Vision Ray Tracer
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Thu, 23 Sep 1999 19:48:42 -0400, "Nathan Kopp" <Nat### [at] Koppcom> wrote:
>And, as mentioned, PS viewers are available...
I will get a PS viewer and try it out. Thanks.
--
Alan
http://www.povray.org - Home of the Persistence of Vision Ray Tracer
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
