Python docs disappointing - group effort to hire writers?
koranthala at gmail.com
Sat Aug 8 09:26:50 CEST 2009
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
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.
More information about the Python-list