Interactive Doc Comments - Their Future?
От | Jonathan S. Katz |
---|---|
Тема | Interactive Doc Comments - Their Future? |
Дата | |
Msg-id | 27B386F2-6DE0-4E2D-A92E-CCBA976E85C1@excoventures.com обсуждение исходный текст |
Ответы |
Re: Interactive Doc Comments - Their Future?
Re: Interactive Doc Comments - Their Future? |
Список | pgsql-www |
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 problemwith. However, I have noticed an interesting pattern with the doc comments that are submitted - they all tend tofall into a few categories: 1. Document spelling / indexing corrections2. Feature Requests3. Requests for clarification4. Advice for the reader5. Statementsthat 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, clarificationsof the documentation, or hints for other users. Please note, this is not a support forum, and your IP addresswill be logged. If you have a question or need help, please see the faq, try a mailing list, or join us on IRC. Notethat submissions containing URLs or other keywords commonly found in 'spam' comments may be silently discarded. Pleasecontact 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 maintainon 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, butwe should be able to make it easy for people to submit thoughts to -docs or other avenues to get submissions in, particularlywhen 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 interactivedocs? Best, Jonathan
В списке pgsql-www по дате отправления: