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

I hate to keep saying, "yes, but...". But!

Where are we going with this? Sure we are grizzled developers, who use
lynx (links is my favourite), emacs and all that stuff to read our docs,
rsync or wget to update them, and we live in SSH consoles. We have the
advantage of actually knowing all the ins and outs of SQL and all the
various Pg functions.

So what's the next step? Do we keep the docs as is with minor
improvements as the backend gets upgraded from one version to the next,
or do we really step up to the plate and make Postgresql accessible to
many new users? Do we stay behind or move forward? Is where we are good
enough now?

What's next? Do we keep arguing about how it meets our needs now, or
look at moving forward to meet the needs of the next crop of new users
who think MySQL sucks, but need better documentation?

- Ericson


Keith C. Perry wrote:

>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
>>
>>
>>
>
>
>
>