[Python-Dev] documenting things [Was: Re: Proposal: defaultdict]

[Bengt Richter]

On Mon, 20 Feb 2006 12:01:02 +0000, "Paul Moore" <p.f.moore at gmail.com> wrote:

>On 2/19/06, Steve Holden <steve at holdenweb.com> wrote:
>> > You are missing the rationale of the PEP process. The point is
>> > *not* documentation. The point of the PEP process is to channel
>> > and collect discussion, so that the BDFL can make a decision.
>> > The BDFL is not bound at all to the PEP process.
>> >
>> > To document things, we use (or should use) documentation.
>> >
>> >
>> One could wish this ideal had been the case for the import extensions
>> defined in PEP 302.
>
>(A bit off-topic, but that hit home, so I'll reply...)
>
>Agreed, and it's my fault they weren't, to some extent. I did try to
>find a suitable place, but the import docs are generally fairly
>scattered, and there wasn't a particularly good place to put the
>changes.
>
>Any suggestions would be gratefully accepted...

I've always thought we could leverage google to find good doc information
if we would just tag it in some consistent way. E.g., if you wanted to
post a partial draft of some pep doc, you could post it here and/or c.l.p
with 
PEP 302 docs version 2 <<--ENDMARK--
text here
=========
(use REST if ambitious)
...
--ENDMARK--

If we had some standard tag lines, we could make an urllib tool to harvest the
material and merge the most recent version paragraphs and auto-post it as html
in one place for draft docs on python.org


The same tagged section technique could be used re any documention, so
long as update and/or addition text can be associated with where it should
be tagged in as references. I think mouseover popup hints with clickable js popups
for the additional material would be cool. It would mean automatically editing
the doc to insert the hints though.

Well, nothing there is rocket science, but neither is a wall of bricks
so long and high you can't live long enough to complete it ;-)

Regards,
Bengt Richter