[Doc-SIG] Re: ping Ping

[Edward D. Loper]

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

I tend to agree about ST being too complex in some ways.  I'm currently
working on 2 separate PEPs, one that includes all the features that Tibs
wants, and one that has only a more limited set.  I think that we may
have an easier time selling a simpler proposal to the Python community,
but I may be wrong..  We'll wait until all the PEPs are out on the table,
and discuss them, I guess.

> > > 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.
Good.  We may need more devil's advocates as we get closer to 
agreement, because we'll need to be able to answer these questions
when they come up on python.dev. :)

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

>     - 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 -- how does the user find
the tutorials, howtos, etc., that were *not* written by the 
programmer/maintainer?  Currently, www.python.org does pretty well
at this, but we may want to set up a more principled system..
But in any case, I think this is a separate issue..

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

2 issues: editing and distribution
  distribution -- maybe we want to turn modules into packages, and
     include docs in the package?  There's not a lot of precedent
     for this in other languages though..
  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.

-Edward