Обсуждение: Re: Interactive Documentation - how do you want it towork?
> -----Original Message----- > From: Neil Conway [mailto:neilc@samurai.com] > Sent: 02 February 2003 20:52 > To: Dave Page > Cc: PostgreSQL Hackers > Subject: Re: [HACKERS] Interactive Documentation - how do you > want it towork? > > > 2) Bearing in mind your answer to the previous question, should all > > the comments be deleted when useful examples have been > merged into the > > main documents (remember that the definition of 'useful' > may vary), or > > should we only remove the 'junk' ones? > > Once the comment's suggestion has been incorporated and the > docs updated, I think it should be removed. Just like in the > rest of the documentation, there's no point presenting > duplicate content to the user, so we should only keep the > idocs comments that are still relevant. The same goes for > comments that have no value (e.g. support requests). My concern here is that what (for example) Bruce decides is not a useful addition to the docs themselves, maybe something that would have helped me with some bizarre problem. If we dump *all* the docs after they have been merged then I might lose that helpful tip. Also, and perhaps more importantly, the comments will be merged into a *future* version. If I am running 7.2, I'm going to look at the 7.2 docs, not 7.3. Regards, Dave.
Dave Page wrote: > My concern here is that what (for example) Bruce decides is not a useful > addition to the docs themselves, maybe something that would have helped > me with some bizarre problem. If we dump *all* the docs after they have > been merged then I might lose that helpful tip. > > Also, and perhaps more importantly, the comments will be merged into a > *future* version. If I am running 7.2, I'm going to look at the 7.2 > docs, not 7.3. We have already had several eyes look at the comment, so I am fairly certain that there isn't anything useful. If there is, someone else will make the same comment, and we will catch it. Ideally, we would have no comments because it would all be in the docs. -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 359-1001+ If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania19073
I don't think I was clear before. When someone is looking at the interactive docs, I would like them to say, "Oh, there's a comment. I better read that in case it will help me." If we have old comments, their "special" value becomes diminished. That's why I think they should be removed as they are reviewed. --------------------------------------------------------------------------- Dave Page wrote: > > > > -----Original Message----- > > From: Neil Conway [mailto:neilc@samurai.com] > > Sent: 02 February 2003 20:52 > > To: Dave Page > > Cc: PostgreSQL Hackers > > Subject: Re: [HACKERS] Interactive Documentation - how do you > > want it towork? > > > > > 2) Bearing in mind your answer to the previous question, should all > > > the comments be deleted when useful examples have been > > merged into the > > > main documents (remember that the definition of 'useful' > > may vary), or > > > should we only remove the 'junk' ones? > > > > Once the comment's suggestion has been incorporated and the > > docs updated, I think it should be removed. Just like in the > > rest of the documentation, there's no point presenting > > duplicate content to the user, so we should only keep the > > idocs comments that are still relevant. The same goes for > > comments that have no value (e.g. support requests). > > My concern here is that what (for example) Bruce decides is not a useful > addition to the docs themselves, maybe something that would have helped > me with some bizarre problem. If we dump *all* the docs after they have > been merged then I might lose that helpful tip. > > Also, and perhaps more importantly, the comments will be merged into a > *future* version. If I am running 7.2, I'm going to look at the 7.2 > docs, not 7.3. > > Regards, Dave. > > ---------------------------(end of broadcast)--------------------------- > TIP 2: you can get off all lists at once with the unregister command > (send "unregister YourEmailAddressHere" to majordomo@postgresql.org) > -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 359-1001+ If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania19073