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

Hello all,

am I the only one preferring plain old printed documentation? Or do you
all have 55 inch gigapixel displays being able to show browser based
documentation, an editor, a debugger and the application to be
developed at the same time?

IMHO HTML or similiar documentation with links and full text search
engines is quite useful to find just the little piece of information
that is missing - or a user´s comment to the documented matter (the
commented PHP online documentation is a good example for that), but if
you seriously develop something, some kind of printed matter is
unbeatable:

You can put it on your desk besides the display, not using precious
space on the display itself;

you can add your own comments and experiences by writing them with a
simple pencil next to the published information;

you can study this kind of documentation without switching on a
computer, nearly everywhere, as long as there is some light.

Of course sometimes fancy search engines may speed up looking for
special information, but these situations are quite rare compared with
the need for the knowledge how things work and can be used.

So if documentation is provided as "browseable" (like HTML), it should
_always_ be acomplished by "printable" equal documentation as well, and
not just HTML without formatting elements but really printable, like
Postscript or PDF, neatly formatted.

YMMV.

Regards, Frank.



On Mon, 29 Dec 2003 16:45:40 -0500 Ericson Smith <eric@did-it.com> sat
down, thought long and then wrote:

> 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@did-it.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.
> >
> >
> >
>


--
Frank Finner

Memory follows memory, memory defeats memory; some things are banished
only into the realms of our rich imaginings  -  but this does not mean
that they do not or cannot or will not exist - they exist! They exist!
                              (M. Moorcock, "The Revenge Of The Rose")