On Aug 7, 5:15 pm, Dave Angel <da...@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. -- http://mail.python.org/mailman/listinfo/python-list
