Re: Is my MySQL Gaining ?

I guess my point is that; should we be pushing to keep the current
documentation, or should we be looking to improve it?

Should we be moving towards short concise pages describing a single
issue that is robustly interlinked, or should we be looking at longer
pages anchored by HTML text that if discovered by a search engine makes
it actually harder to find information since we have to read through the
whole page?

Is it better to catalog 1000 specific pages about 1000 things, or 100
pages about 10 things? Which system would bring a user to the
information they needed faster, if a search engine that positioned users
at the *top* of a document were employed? If presented with a PDF file
or an HTML document on the web, which would you use (consider that you
need the information now, not an hour later)?

Today, we use search engines as the starting point on the web (except
for bookmarked or otherwise memorized pages). Why build systems that
breaks that paradigm, or take advantage of it insufficiently?

Don't get me wrong, I am glad that some documentation is there, but as
many other posters have said, it needs to be better.

- Ericson

Bruno Wolff III wrote:

>On Mon, Dec 29, 2003 at 16:18:38 -0500,
> Ericson Smith <eric(at)did-it(dot)com> wrote:
>
>
>>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?
>>
>>
>
>Then I look though the table of contents to see what sections might
>be relevant and try them in an order based on which I think are most
>likely to give me what I want.
>
>
>
>>>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.
>>
>>
>
>This I find hard to believe. Reading through the manual (with some skimming)
>before doing a lot of work will probably end up saving you time 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 installed copies of the documentation at home and work while installing
>the server. However, I don't use Postgres when not at home or work, so
>the client example doesn't apply to me. In some cases having it on your
>laptop would be useful.
>
>
>
>>>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.
>>
>>
>
>Maybe if you are using google where you won't get placed at the relevant
>part of the page you get pointed to. With a custom search engine, you
>could reference directly to the function's entry within a page.
>
>
>
>>>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?
>>
>>
>
>Because it matches the version installed on that machine. When using
>the documentation on the Postgres site, you need to be concerned about
>looking at the correct copy unless you are mostly running the latest
>release.
>
>
>