 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
> 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
|
|
| |
| |
|
|
|
|
| |
