Re: Interactive Doc Comments - Their Future?

On Mar 5, 2014, at 3:43 AM, Dave Page wrote:

> On Wed, Mar 5, 2014 at 3:33 AM, Jonathan S. Katz
> <jonathan(dot)katz(at)excoventures(dot)com> wrote:
>> Hi Everyone,
>>
>> We have a section on our website for "interactive" documentation, where people can submit their comments on the documentation, and a moderator will go and approve them. Somehow I've become the de facto moderator, which I have no problem with. However, I have noticed an interesting pattern with the doc comments that are submitted - they all tend to fall into a few categories:
>>
>> 1. Document spelling / indexing corrections
>> 2. Feature Requests
>> 3. Requests for clarification
>> 4. Advice for the reader
>> 5. Statements that are just plain wrong
>>
>> The only guidelines we have for submitting interactive docs are as such:
>>
>> "Please use this form to add your own comments regarding your experience with particular features of PostgreSQL, clarifications of the documentation, or hints for other users. Please note, this is not a support forum, and your IP address will be logged. If you have a question or need help, please see the faq, try a mailing list, or join us on IRC. Note that submissions containing URLs or other keywords commonly found in 'spam' comments may be silently discarded. Please contact the webmaster if you think this is happening to you in error."
>>
>> Currently I try to handle these scenarios as such:
>>
>> #1, sometimes #3 - relay to someone working on docs
>> #2, #5 - reject
>> #4 - approve if it seems relevant, otherwise reject
>>
>> So this begs a few questions:
>>
>> * What are the goals for having the interactive docs around?
>> * Are they actually useful?
>> *Is it something we wish to maintain on the website?
>> * If we do remove them, do we want to have better guidance on the static docs on where to submit corrections / feature requests / etc?
>>
>> My personal thoughts from reading what is submitted is that the doc comments are not that useful and should be removed, but we should be able to make it easy for people to submit thoughts to -docs or other avenues to get submissions in, particularly when they are on a particular document page.
>>
>> But of course, I think this would make for a good discussion :-) So - what, if anything, should we do with the interactive docs?
>
> They were originally inspired by the comment system on the PHP doc
> website, which if you've ever hacked with PHP you'll probably agree is
> an invaluable resource - however, that's largely because the PHP docs
> just aren't great (IMHO, YMMV etc. etc.).

I kind of figured they were inspired by the PHP docs, and yes, I totally agree that the PHP comments were definitely a welcome supplement to the documentation, particularly PHP4 (IMHO, YMMV, etc. etc., to borrow your phrase)

> Having user submitted code
> examples and additional explanation is very useful. Our docs are far
> better however, so naturally the comments are less useful. That said,
> I have, on odd occasions, found them to be helpful. Personally, I'd
> vote for keeping them, if you or others are happy to continue with the
> moderation tasks.

I am sure there are past examples that are helpful, but the issue is what we are getting with the current submissions, a lot of which are requests for clarification or additions more suited for -general, #postgresql or even -docs.

With that said, does anyone involved with -docs pay attention to new comments? I'm not sure if an alert is sent over there. If it is, it makes the submissions much more useful and allows for a level of interactivity.

Jonathan