Python docs disappointing - group effort to hire writers?

[koranthala]

On Aug 7, 5:15 pm, Dave Angel <da... at ieee.org> wrote:
> alex23 wrote:
> > Paul Rubin <http://phr...@NOSPAM.invalid> wrote:
>
> >> The PHP docs as I remember are sort of regular (non-publically
> >> editable) doc pages, each of which has a public discussion thread
> >> where people can post questions and answers about the topic of that
> >> doc page.  I thought it worked really well.  The main thing is that
> >> the good stuff from the comment section gets folded into the actual
> >> doc now and then.
>
> > I'd still like to see this kept out of the official docs as much as
> > possible, mostly for reasons of brevity & clarity. I think the
> > official docs should be considered definitive and not require a
> > hermeneutic evaluation against user comments to ensure they're still
> > correct...
>
> > How about a secondary site that embeds the docs and provides
> > commenting functionality around it? That's certainly a finitely scoped
> > project that those with issues about the docs could establish and
> > contribute to, with the possibility of it gaining official support
> > later once it gains traction.
>
> I share your concern about unmonitored comments.  However, it seems a
> useful possibility would be for the "official" pages to each have
> specially-marked links that possibly lead to such user comments.  
> Clearly they'd have to marked carefully, so that naive users don't
> confuse the two.  But otherwise, it feels like a good idea.
>
> In my case, I usually access the docs via the Windows help file.  So
> it'd be quite easy for me to recognize that once I've gotten to a
> browser page, I'm not in Kansas any more.  But that could be also
> accomplished by having a very different stylesheet for the user comments
> page.
>
> DaveA

The best example that I have seen is djangobook.
The comment system in it is quite exquisite.
It would be good for the Python docs to have such a mechanism.