[Doc-SIG] Re: ping Ping

[Ka-Ping Yee]

On Sat, 17 Mar 2001, Edward Welbourne wrote:
> Hello, Ping, where are you ?
> We need your response to our gabblings.

Hi, Eddy.

I'm sorry i haven't had time to really particpate in this discussion
this past week.  I've been watching all the e-mail go by but haven't
formulated my responses yet.  I was originally considering writing my
own PEP if i could find the time.

Thanks for the invitation.

My general feeling about all of the syntax ideas that have been going
back and forth is that i'm a little afraid of their complexity.  When
i have a moment i'll try to get a handle on what rules are currently
on the table and see how many there are, but i'll definitely want to
keep them minimal.

> ah.  So: Edward, Tibs and I, who have done this week's talking, all
> agree on a position which puts `API docs' into the source file and puts
> tutorials, reference docs, etc. elsewhere.

I will maintain the opposing position for now, as devil's advocate.
Here are some points to consider, just off the top of my head:

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

    - If documentation lives in the modules, we can guarantee
      that any user of the module has the information they
      need to understand and use it properly.

    - Allowing extended documentation in a module does not
      preclude other people from writing other documents,
      tutorials, books, etc. on a particular topic.

    - If documentation for a module doesn't live in the module
      itself, how will a user find it?  One source of motivation
      for this suggestion was running "perldoc CGI" -- having a
      copy of CGI.pm guarantees that you have an instantly
      available and fairly comprehensive description of all the
      things you can do with CGI.pm.

    - Keeping modules and associated docs in the same file helps
      to ensure that the two are in sync when you distribute or
      edit the file.  (It's not possible to have different
      versions of the code and the docs at the same time; it's
      less likely that someone will check in changes to one
      without updating the other, etc.)


-- ?!ng