Re: Interactive Doc Comments - Their Future?

On Wed, Mar 5, 2014 at 4: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
>

In my experience, a lot of othem fall under either #5, or under the
category of repeating something that's already on the page.

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're not particularly interactive today. They're a one way submission,
and then a moderator.

Perhaps what we could do is replace them with something that works like the
bug report form. So instead of submitting a comment into a static space,
they turn into an email to the -docs list, which can then get discussion
around it and eventually turn it into a modifications for the actual docs?

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/