[Doc-SIG] Re: ping Ping

[Ka-Ping Yee]

On Wed, 21 Mar 2001, Edward D. Loper wrote:
> >     - Just to be clear, the suggestion on the table is only to
> >       move the library ref manual into the modules, not the
> >       language reference or anything like that.
> 
> Only the ref manual, or also the howtos, tutorials, etc?  And if
> only the ref manuals, what do we currently think belongs in the
> ref manuals, other than API docs?

What i had in mind was "how to use this module".

Let's look at some examples for clarification.

As an extreme example, try running "perldoc CGI".  CGI.pm contains
about 3200 lines of code followed by 3000 lines of detailed
documentation.  While the module itself is indeed enormous, i think
that it is useful to have all of that information about how to use
the CGI module instantly available right there in CGI.pm.

A more reasonable arrangement would be to split the CGI functionality
into several modules, and move the relevant parts of the docs
acoordingly.  For instance, CGI.pm currently tries to do the work of
both cgi.py and HTMLgen.  But *if* CGI is going to do all that, it
should all be documented in CGI.pm.

Look at the sections in these examples and give an opinion on what
belongs or doesn't belong with the source code:

    perldoc CGI
    perldoc CPAN
    perldoc CGI::Cookie
    perldoc Data::Dumper
    perldoc Getopt::Long
    perldoc Net::Ping
    perldoc overload

> >     - If documentation for a module doesn't live in the module
> >       itself, how will a user find it?  
> 
> I think that this is a question that we'd have to answer, whether
> we put more docs in the module or not

I think it's relevant.  The question is "how far is the user of a
module from *some* information on how to use the module?"  Doesn't
matter if they don't have every article that anyone has ever
written about the module -- do they have a starting point?

>   editing -- I think that keeping modules & docs in the same file
>      will help keep docs in sync with modules *if* we're talking
>      about what has been called "point-documentation"...  But I
>      don't think it'll help for howtos, tutorials, etc.  It's 
>      unreasonable to edit the tutorial every time you change the
>      code.

If changing the code changes the behaviour of the module so that
your examples don't work any more, then yeah, you'd better edit
the examples.  (Scenario: i've changed a method name from foo() to
spam(), so in my editor i search for ".foo(" to do replacement...)

It's also harder for me to change foo() to spam() in just the code,
check in just that part, and say "oh, i'll change the docs later" --
because i'll be checking in a single file that's inconsistent with
itself.



-- ?!ng

Happiness comes more from loving than being loved; and often when our
affection seems wounded it is is only our vanity bleeding. To love, and
to be hurt often, and to love again--this is the brave and happy life.
    -- J. E. Buchrose