[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

Re: graphing/charting application

seebs

7/15/2007 9:34:00 PM

In message <20070715212911.GC18755@demeter.hydra>, Chad Perrin writes:
>RDoc were written specifically to ease the process of creating
>documentation, to provide a solid beginning to that documentation so that
>half the work is already done for someone that intimately knows the
>software, but the end result is that many people seem to think that *is*
>the documentation and never bother finishing the job. Documentation is
>an important part of any development effort -- almost as important as the
>software itself. Documentation is important for the same reason readable
>code is important, and yet people who will argue for days on end about
>the best way to eke that last bit of readability out of code will turn
>around and go on producing software without even the most rudimentary
>attempt to make documentation clear and useful.

I think many developers underestimate the significance of documentation
to projects. Of course, most of us have at least some practice figuring
things out without documentation, reading source, and so on...

But putting in a few years as a writer leaves me more concerned with
documentation than I used to be. I'll say that much.

-s
3 Answers

Tim Hunter

7/15/2007 10:39:00 PM

0

Peter Seebach wrote:
> I think many developers underestimate the significance of documentation
> to projects. Of course, most of us have at least some practice figuring
> things out without documentation, reading source, and so on...
>
> But putting in a few years as a writer leaves me more concerned with
> documentation than I used to be. I'll say that much.
>
+1. I did my time, too, helping document a C compiler/linker on a system
that had never had a C compiler/linker before. Then I worked in a
publications department for 3 years and got to see the other side, how
developers (generally) treat writers, which is to say, not well. This
left me with much more respect for the writer's point-of-view. A
dedicated and skilled writer can do a lot to make the software successful.

Hobbyist software does not require documentation. Developers are
certainly free to simply throw it over the wall and say "here, take it
or leave it." But users are also free to evaluate the software by the
quality of its documentation.

--
RMagick OS X Installer [http://rubyforge.org/project...]
RMagick Hints & Tips [http://rubyforge.org/forum/forum.php?for...]
RMagick Installation FAQ [http://rmagick.rubyforge.org/instal...]

Chad Perrin

7/15/2007 10:42:00 PM

0

On Mon, Jul 16, 2007 at 06:34:22AM +0900, Peter Seebach wrote:
> In message <20070715212911.GC18755@demeter.hydra>, Chad Perrin writes:
> >RDoc were written specifically to ease the process of creating
> >documentation, to provide a solid beginning to that documentation so that
> >half the work is already done for someone that intimately knows the
> >software, but the end result is that many people seem to think that *is*
> >the documentation and never bother finishing the job. Documentation is
> >an important part of any development effort -- almost as important as the
> >software itself. Documentation is important for the same reason readable
> >code is important, and yet people who will argue for days on end about
> >the best way to eke that last bit of readability out of code will turn
> >around and go on producing software without even the most rudimentary
> >attempt to make documentation clear and useful.
>
> I think many developers underestimate the significance of documentation
> to projects. Of course, most of us have at least some practice figuring
> things out without documentation, reading source, and so on...

True. It's a shame that there isn't better documentation for some
projects, however -- especially since that often means someone will go
use something else (with better documentation) instead. While I could
eventually puzzle out how to use Gruff effectively, for instance, I'd
rather have something with good documentation at my fingertips than have
to pore over source code just for a trivial use of the library.

Since I've been accused of something akin to solipsism before in this
discussion, I'll be clear: I'm not saying that I, personally, am an
important user to whom developers must cater. Read my personal
experience as a symptom of a deeper problem with the lack of quality
documentation, please.


>
> But putting in a few years as a writer leaves me more concerned with
> documentation than I used to be. I'll say that much.

Writing what amounts to tutorial documentation for money in the last few
years has certainly improved my understanding of the importance of
documentation -- but I think the biggest change to my perspective is in
the fact that I'm using libraries much more these days than I used to,
and thus finding poor library documentation far more problematic than I
used to.

--
CCD CopyWrite Chad Perrin [ http://ccd.ap... ]
Marvin Minsky: "It's just incredible that a trillion-synapse computer could
actually spend Saturday afternoon watching a football game."

list. rb

7/16/2007 12:17:00 AM

0

This may be OT at this point on the conversation but, I've used XML/
swf charts for quite a while now and really like it

Sent from my iPhone

On Jul 15, 2007, at 6:42 PM, Chad Perrin <perrin@apotheon.com> wrote:

> On Mon, Jul 16, 2007 at 06:34:22AM +0900, Peter Seebach wrote:
>> In message <20070715212911.GC18755@demeter.hydra>, Chad Perrin
>> writes:
>>> RDoc were written specifically to ease the process of creating
>>> documentation, to provide a solid beginning to that documentation
>>> so that
>>> half the work is already done for someone that intimately knows the
>>> software, but the end result is that many people seem to think
>>> that *is*
>>> the documentation and never bother finishing the job.
>>> Documentation is
>>> an important part of any development effort -- almost as important
>>> as the
>>> software itself. Documentation is important for the same reason
>>> readable
>>> code is important, and yet people who will argue for days on end
>>> about
>>> the best way to eke that last bit of readability out of code will
>>> turn
>>> around and go on producing software without even the most
>>> rudimentary
>>> attempt to make documentation clear and useful.
>>
>> I think many developers underestimate the significance of
>> documentation
>> to projects. Of course, most of us have at least some practice
>> figuring
>> things out without documentation, reading source, and so on...
>
> True. It's a shame that there isn't better documentation for some
> projects, however -- especially since that often means someone will go
> use something else (with better documentation) instead. While I could
> eventually puzzle out how to use Gruff effectively, for instance, I'd
> rather have something with good documentation at my fingertips than
> have
> to pore over source code just for a trivial use of the library.
>
> Since I've been accused of something akin to solipsism before in this
> discussion, I'll be clear: I'm not saying that I, personally, am an
> important user to whom developers must cater. Read my personal
> experience as a symptom of a deeper problem with the lack of quality
> documentation, please.
>
>
>>
>> But putting in a few years as a writer leaves me more concerned with
>> documentation than I used to be. I'll say that much.
>
> Writing what amounts to tutorial documentation for money in the last
> few
> years has certainly improved my understanding of the importance of
> documentation -- but I think the biggest change to my perspective is
> in
> the fact that I'm using libraries much more these days than I used to,
> and thus finding poor library documentation far more problematic
> than I
> used to.
>
> --
> CCD CopyWrite Chad Perrin [ http://ccd.ap... ]
> Marvin Minsky: "It's just incredible that a trillion-synapse
> computer could
> actually spend Saturday afternoon watching a football game."
>