Re: [GENERAL] Is my MySQL Gaining ?

On this very topic, and digressing a little, I lost track of the
XML/Jade PDF document problems thread as it moved across different
lists. Was that ever resolved, or will the 7.4 PDF docs still be
sometime off?

T.

Frank Finner wrote:

>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(at)did-it(dot)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(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.
>>>
>>>
>>>
>>>
>>>
>
>
>
>