public inbox for [email protected]  

help / color / mirror / Atom feed

From: Nikolay Samokhvalov <[email protected]>
To: Magnus Hagander <[email protected]>
Cc: Alvaro Herrera <[email protected]>
Cc: [email protected]
Cc: PostgreSQL-documentation <[email protected]>
Subject: Re: [DOCS] Users comments don't migrate to docs for new version?
Date: Fri, 8 Jun 2007 01:18:58 +0400
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
	<[email protected]>
	<[email protected]>

On 6/6/07, Magnus Hagander <[email protected]> wrote:
> Alvaro Herrera wrote:
> > The thing to do in these cases is to move the useful info from the user
> > comments into the main doc text.
>
> Yeah, that's the idea. Tom often goes through the comments and puts
> stuff into the docs. But I'm sure there are a *lot* of other people who
> could help with that as well - read comments, figure out of they make
> sense, and submit a docs patch for the next version!
>
> //Magnus

But I suppose there are some cases when it's not possible to move the
comment to the main text -- e.g. if the comment concerns too narrow
area, is very specific and is useful not for all people (but still
useful for some!).

Moreover, moving good comments to the main text makes the text bloated
-- what if we have 10 examples of using function aaa() and all of them
are illustrations for different areas? We (ok, sorry, Tom because only
he knows English) will choose only 1 of them to avoid bloating of the
main text, even if all 10 use cases has some specific features...

Users comment collection is a good thing! Ask any PHP developer --
many of them will say that user comments that the main manual has are
something like cookbooks -- lots of useful      recipes.

I could help with (yeah, not with reworking comments -- I do not know
English well :-) ) creating a simple patch that adds a notice "this
comment was originally created for version 8.0" and maybe something
else in this direction -- these my thoughts are not fresh, I always
lacked good user comments... BTW, then we would add some
marking/rating system to the comments to allow other users see what
comment is really useful.

--
Best regards,
Nikolay

view thread (14+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected], [email protected]
  Subject: Re: [DOCS] Users comments don't migrate to docs for new version?
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox