Обсуждение: Re: [GENERAL] Re: PostgreSQL vs Oracle vs DB2 vs MySQL - Which should I use?

Tom Lane writes:

> Aside from persuading more people to spend time answering email
> questions, 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.  The main problem is to get the work done.  We need volunteers to
> actually do some of these things, not just suggest them ...

One thing we should try to do in the future (i.e., the next big attack I
have on you) is to maintain a human-edited concept index for the docs,
like every good non-fiction book has at the end.  The technical details
for this are mostly worked out, it just needs someone to compose a list of
all "concepts" and find all the places where they're discussed.

This might even be something to stick in for the 7.1.1 release, because
otherwise there will be another 8 month lag before it becomes useful.

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/

Peter Eisentraut <peter_e@gmx.net> writes:
> One thing we should try to do in the future (i.e., the next big attack I
> have on you) is to maintain a human-edited concept index for the docs,
> like every good non-fiction book has at the end.  The technical details
> for this are mostly worked out, it just needs someone to compose a list of
> all "concepts" and find all the places where they're discussed.

The large documents I've done in the past (product manuals and such)
used automatic index generation in LaTeX.  You add a tag to text that
needs an index entry:

    To fix this problem, frobnitz the foobar<index>foobar</index>.

and then the index will have an entry for "foobar" that references this
page, along with any other pages where <index>foobar</index> appears.
<index>foobar</index> doesn't affect the visible text on the page
however.

Assuming that our SGML tools can do something similar, this would seem
like the way to go.  Getting the docs marked up initially would be a
painful task, but once it's done it'd be relatively easy for doco
contributors to include appropriate index entries in new text.

I think an index that's maintained separately from the text proper would
be doomed to failure ...

            regards, tom lane

> > Aside from persuading more people to spend time answering email
> > questions, 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.  The main problem is to get the work done.  We need volunteers to
> > actually do some of these things, not just suggest them ...

Maybe the PHP.net people would be kind enough to allow you guys to use their
annotated manual software...

Chris

On Mon, Feb 19, 2001 at 09:24:59AM +0800, Christopher Kings-Lynne wrote:
> > > Aside from persuading more people to spend time answering email
> > > questions, 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.  The main problem is to get the work done.  We need volunteers to
> > > actually do some of these things, not just suggest them ...
>
> Maybe the PHP.net people would be kind enough to allow you guys to use their
> annotated manual software...

Be careful, it is based on MySQL :)

-Egon

--
http://www.linuxtag.de/
http://php.net/books.php
http://www.concert-band.de/
http://www.php-buch.de/