Re: [GENERAL] Annotatable on-line documentation
Peter Eisentraut wrote: Richard writes: Would this lighten the work load on the folk that are currently maintaining the docs? Would it lighten the work load for the core developers? Would it stimulate the development of richer documetation? Would it draw some of the load off the mailing lists? My concerns are mostly that that kind of thing would be abused as a discussion forum, the quality of the comments is quite low on average, and the added efforts to weed out the posts on a regular basis seem prohibite. I don't see any particular advantage coming from this that couldn't be achieved in another way. Well, one thing would be is that it would make it easier for other people to submit changes to a particular page on the docs. You can just go there and submit a change. Sending a patch much harder. Maybe, as someone else suggested, a moderated one. That would stop the discussion problem. -- Martijn van Oosterhout [EMAIL PROTECTED] http://cupid.suninternet.com/~kleptog/
Re: [GENERAL] Annotatable on-line documentation
Martijn van Oosterhout writes: Well, one thing would be is that it would make it easier for other people to submit changes to a particular page on the docs. You can just go there and submit a change. Sending a patch much harder. The policy for documentation submissions has always been "Give us words and we'll do the rest." -- Peter Eisentraut [EMAIL PROTECTED] http://yi.org/peter-e/
[GENERAL] Annotatable on-line documentation
(This was: "Re: [GENERAL] Re: PostgreSQL vs Oracle vs DB2 vs MySQL - Which should I use?", but I think a new thread has spun off...) [Tom Lane said ...] I agree we need to work harder on making answers findable outside the mailing lists. Improving the docs, making the mail archives more easily searchable, etc etc. I dunno if an "annotated manual" would help --- I've never used one --- but if people want to try one, it can't hurt. [... to which Bruce Momjian added ...] I will say that the FAQ and my book have visibly reduced the number of questions. When I put something on the FAQ, the questions about that topic just magically go away. I have not used an annotated document either. However, I could see such a beast being used in the development of the documentation in a way that is not dissimilar to the development of the product itself. That is, I see an annotatable set of documentation as similar in nature to the developmental version of the product. After some period of development, some lucky editor(s) would fold the annotations into the document proper, periodically releasing the "stable" version of the docs. Would this lighten the work load on the folk that are currently maintaining the docs? Would it lighten the work load for the core developers? Would it stimulate the development of richer documetation? Would it draw some of the load off the mailing lists? A pilot project may be enlightening. Anyone have experience with setting up/maintaining annotatable on-line documentation? Cheers, Richard Blackwell Programmer/Analyst Simon Fraser University Burnaby, BC Canada __ Do You Yahoo!? Get personalized email addresses from Yahoo! Mail - only $35 a year! http://personal.mail.yahoo.com/
Re: [GENERAL] Annotatable on-line documentation
You should have a look at the wiki stuff http://c2.com/cgi/wiki?WikiWikiWeb Dave - Original Message - From: "Richard" [EMAIL PROTECTED] To: [EMAIL PROTECTED] Sent: Friday, February 16, 2001 12:40 PM Subject: [GENERAL] Annotatable on-line documentation (This was: "Re: [GENERAL] Re: PostgreSQL vs Oracle vs DB2 vs MySQL - Which should I use?", but I think a new thread has spun off...) [Tom Lane said ...] I agree we need to work harder on making answers findable outside the mailing lists. Improving the docs, making the mail archives more easily searchable, etc etc. I dunno if an "annotated manual" would help --- I've never used one --- but if people want to try one, it can't hurt. [... to which Bruce Momjian added ...] I will say that the FAQ and my book have visibly reduced the number of questions. When I put something on the FAQ, the questions about that topic just magically go away. I have not used an annotated document either. However, I could see such a beast being used in the development of the documentation in a way that is not dissimilar to the development of the product itself. That is, I see an annotatable set of documentation as similar in nature to the developmental version of the product. After some period of development, some lucky editor(s) would fold the annotations into the document proper, periodically releasing the "stable" version of the docs. Would this lighten the work load on the folk that are currently maintaining the docs? Would it lighten the work load for the core developers? Would it stimulate the development of richer documetation? Would it draw some of the load off the mailing lists? A pilot project may be enlightening. Anyone have experience with setting up/maintaining annotatable on-line documentation? Cheers, Richard Blackwell Programmer/Analyst Simon Fraser University Burnaby, BC Canada __ Do You Yahoo!? Get personalized email addresses from Yahoo! Mail - only $35 a year! http://personal.mail.yahoo.com/
