Re: Is my MySQL Gaining ? - Mailing list pgsql-general

Quoting Ericson Smith <eric@did-it.com>:

> Bruno Wolff III wrote:
>
> >Once you know where to look for stuff it isn't that hard to find things.
> >
> >
> >
> Yes, but what happens where you don't know where to look for stuff?

Fair enough- the search engine definitely are problematic and the main site
probably needs to be reorganized to clearly identify the most important URLs.

> >This is one of the advantages of reading through the whole manual once
> >to get an idea of whats there.
> >
> >
> Sure, but who has time to read through a whole manual first? No system I
> ever learned had me do that.

I'm not a very versused in Oracle but I know that when I used to spec hardware
for them the company I was with pretty much wanted us to read everything we
could get our hands on.

People absolutely should "read" the manual in at least 2 passes.  The 1st to get
and overview and feel for how the documentation is put together and a 2nd
(probably on some specific topics first) to get the nuts and bolts how to do
something.  I personally don't feel we should like Bruno said early people NOT
reading the manual.  Saying you have not had to do that before is not really a
reason.  Its counter-productive in the long run.

> >When I need to look things up for Postgres I use a local copy of the web
> >based documentation.
> >
> >
> A good idea. But If you work for different locations (home, client's
> office, office), then that becomes redundant. Besides I would be
> responsible for syncing the manual from PG to each location. Besides, a
> local copy would not usually have a search engine built in.

I don't see how that is redundant unless you mean, you'd have to download things
to multiple sites.  You're right that is not the way to go.  I think most people
get these days that the provided documentation is snapshot and will change but I
for one would not want to be online while I was riding the train to NY to look
up something that I could have cached locally.  The website is the master and
the freedom to "sync" (e.g. download) is your choice.

> >I don't like this. It will make scrolling through a group of related
> >functions harder. Name anchors can be used to allow links directly to
> >functions.
> >
> >
> Nope. I disagree with this one. It makes finding stuff easier if you
> type "nextval()" into a search engine, and it takes you directly to the
> nextval page.

I'm not sure how the search function works but I don't see how these two things
are mutually exclusive.  One function per page would definitely take the context
away from where and how you might use a certain functions.  I would think in the
interest of orderly presentation we would want to group things while still being
able to go directly to the function in question.

(I've never have a problem searching the documents actually.  I think the search
engine there is quite good since it hit multiple versions.)

> >Do you see these two points as applying to only the copy of the
> >documentation on the Postgres web site, or do you see this being
> distributed
> >either with the database (as the current documentation is) or as
> >a separate item (like some of the clients are)?
> >
> >
> >
> In this case, documentation on the website should always be primary.
> Almost anyone working on modern software is always connected to the
> internet. A static copy of the interactive documentation can always be
> distributed with the software. But do many people even refer to the
> included documentation? To be honest, I dont. The documentation in psql
> (eg: \h COPY) is as far as i'll go, the next step in the main site, or
> google. Why rely on documentation on your hard disk that will get out of
> date soon anyway?
>
> - Ericson Smith
>


--
Keith C. Perry, MS E.E.
Director of Networks & Applications
VCSN, Inc.
http://vcsn.com

____________________________________
This email account is being host by:
VCSN, Inc : http://vcsn.com