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.