Re: perl and the culture of libraries

[Note: parts of this message were removed to make it a legal post.]

OTOH, _why is a performance artist, poet, and genius.
A very high bar for us nerdy anti-social shmoes who usually have trouble
coming up with something more creative than "Happy Birthday".

Peter Fitzgibbons
(847) 687-7646
Email: peter.fitzgibbons@xxxxxxxxx
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: pjfitzgibbons@xxxxxxxxxxx
IM AOL: peter.fitzgibbons@xxxxxxxxx


On Tue, Aug 5, 2008 at 10:24 AM, Shadowfirebird <shadowfirebird@xxxxxxxxx>wrote:

_Why does a good job of this sort of thing, when he nails the syntax
of, say Hpricot or sqlite in a couple of pages. Really I think that
is the sort of thing that we should be aiming towards.

http://whytheluckystiff.net/articles/aQuickGuideToSQLite.html

On Tue, Aug 5, 2008 at 3:54 PM, Martin DeMello <martindemello@xxxxxxxxx>
wrote:
On Tue, Aug 5, 2008 at 7:43 AM, Shadowfirebird <shadowfirebird@xxxxxxxxx>
wrote:
I don't wish to be critical (I really don't! That's not just a way of
opening a sentence!) but in my experience there's very little
documentation in Ruby at all. And I'm not convinced that having a
little form with each gem giving the name of the author and a brief
description of what it does is going to help that much. Authors that
want to include that are already finding ways of including it in the
rdoc, usually in some sort of 'readme' entry.

[...]

3) Yes, I'm aware of rdoc. But I'm sorry, that's not really
documentation. It's just a way of reading the comments without having
to wade through the code. For some people, it's all that is needed.
But for others it's just confusing.

You can't have it both ways :) And this is indeed the specific problem
I would like to address - rdoc is too tied into the code, and a readme
file isn't structured enough to get past the blank canvas effect -
it's a mental effort to decide what to put into it.

martin





--
All you can do is try to know who your friends are as you head off to
the war / Pick a star on the dark horizon and follow the light



.

Relevant Pages

  • Re: perl and the culture of libraries
    ... say Hpricot or sqlite in a couple of pages. ... is the sort of thing that we should be aiming towards. ... documentation in Ruby at all. ... I would like to address - rdoc is too tied into the code, ...
    (comp.lang.ruby)
  • Re: ISO electronic versions of A2 tech docs
    ... Documentation ... GS-24 MPW-IIGS ORCA:C ... Beep ... Sort ...
    (comp.sys.apple2)
  • tamely research this vocational medicine
    ... Otherwise the assertion in Ismat's documentation might eat some ... regulatory threats. ... toss random currents sort of Pervez's queue. ... Others comparatively compare. ...
    (sci.crypt)
  • Re: Improvements to RDoc (ideas for GSoC)
    ... and work on something related to RDoc. ... information on a specific feature, and a more general documentation, ... don't really need the second part, but as I was designing a ACL plugin ... This kind of layout is already implemented by Noobkit. ...
    (comp.lang.ruby)
  • how to get rdoc documentation with merb_generator?
    ... Our company spent a year programming with hardly any documentation. ... spent the last two weeks adding this in rdoc format to the controller ... The newer branch has apps for which merb-gen generated a doc directory ...
    (comp.lang.ruby)