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
--
http://mail.python.org/mailman/listinfo/python-list
