List:General Discussion« Previous MessageNext Message »
From:jonathan michaels Date:April 12 1999 7:25am
Subject:Re: FAQ vs Manual
View as plain text  
On Sun, Apr 11, 1999 at 12:41:24PM -0500, Ed Carp wrote:

> > book now that wouldbe an idea, i have found teh html
> > "documentation" if you can use that for for a bunch of html
> > files to be very heavy going.
> 
> That's because you're probably not getting it from the right place.  There's

these were the ones i was refering to in particular.

> only two pages you really need: http://www.mysql.com/Manual/manual_toc.html
> which is the table of contents, and http://www.mysql.com/Manual/manual.html
> which is the actual manual itself.  That's only two files, not "a bunch".

if you wish to be pedanitc ain a peculuarly american fashion 
please feel free.

the stuff at www.mysql.com looke like someting i could have 
thrown together in a few days, or a week and a bit if i had to 
do it my self .. back when i was employed as a systems guy in 
teh 70's and 80's.

as far as good documentation is cncerned that stuff doesnt 
rate very highly, please note the majority of teh stuff put 
out thes days falls into this catagory, and all but one item 
of teh linux stuff has very bad documentation, if it has 
documentation at all.

when i was a young and up and comming buck like mst the the 
people who are going to hack me up saying what ive said .. i 
used to get rapped over teh knuckles severly by my supervisor 
for delviveing 'unfinish' projects. back then the view was that 
a finished project included a documentation set that included a 
significant section of system interactions and pososble fallout 
and or system wide corruption failsafes.

i can only judge software by teh standards that i know, and the 
reader would need be rimined that i've been an analyst and 
business consultant in this field fro as long as most of teh 
particiapats have beel alive, let alone out of shorts, as teh 
old saying goes.

when my pension wil allows me teh privaledge of a good 21 inch 
monitor and my overal health allows me to string 4 to 6 hour 
days togehter without the resulatant week in bed i will rebuild 
teh document set om  www.mysql.com/manual.... as good 
standalone documentation and as a searchable wais document tree.

with regrads to teh other posts concering usng a browser, teh 
problems is that browsers were never designed to be docuent 
delivery systems, while it is possible to use same for samll 
documentation sets teh mysql set if a very good example who it 
should not be done and of teh blatantly obvious shortfalls.

to those of you who would cherish this as an attack, please 
note programmers varey rarely make good document wtiters and as 
a result have poor douementation, software requires good 
doumentation to be genuinely usefull and thsi is where this 
whole open source sham falls over quite badly. the software 
might be ok, but it is only on half or one throd of teh 
packaage, teh rest lies in teh the hands of teh documentation 
writer .. of whom little is ever heard and notong seen. 

anyway, i'd better lay down before i fall of my perch and hurt 
th floor.

in closing, these are the opinions of a long time systems 
developer and documentation organiser. one now cripled with 
sever neurologicaly induced arthritis.

also, i've taken dilivery of my pentium pro (a gift froma 
friend) and will be installing beos v4 shortley, this will give 
me some of teh documentation tools i need, as well as a new 
platform for mysql to investigate.

if anyone knowsa bit about wais and or real documentation 
preperation, please email off teh list and we can discuss teh 
issues with out having to justfiy any noses we may put ot of 
joint .. in th process of rebuilding.

ps, with regards to my earlier comments, monty has pointed me 
to a good place to start, a postscript (a4) version of teh 
documentation. hopefully this will be better than teh poor html 
version.

regards

jonathan

-- 
===============================================================================
Jonathan Michaels
PO Box 144, Rosebery, NSW 1445 Australia
===========================================================<jon@stripped>

Thread
How to switch users.Srini Bhamidipaty9 Apr
  • Re: Problem connecting to db in MySql from Java codeDavid Halsted15 Sep
Re: How to switch users.Fred Lindberg9 Apr
  • RE: How to switch users.Srini Bhamidipaty9 Apr
RE: How to switch users.Fred Lindberg9 Apr
  • Creating a SQL script to generate tables.Srini Bhamidipaty9 Apr
    • RE: Creating a SQL script to generate tables.Jay Miller9 Apr
      • RE: Creating a SQL script to generate tables.Srini Bhamidipaty9 Apr
        • Re: Creating a SQL script to generate tables.Thimble Smith9 Apr
Re: Creating a SQL script to generate tables.Fred Lindberg9 Apr
  • FAQ vs Manual (was: Re: Creating a SQL script...)S. Whitmore10 Apr
Re: FAQ vs Manual (was: Re: Creating a SQL script...)Fred Lindberg10 Apr
  • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Ed Carp11 Apr
  • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Michael Widenius11 Apr
    • Re: FAQ vs ManualPeter F. Brown11 Apr
      • Re: FAQ vs Manualjonathan michaels11 Apr
  • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Ed Carp11 Apr
  • Re: FAQ vs Manual (was: Re: Creating a SQL script...)kalle volkov11 Apr
    • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Steve Edberg11 Apr
      • Re: FAQ vs ManualPaul DuBois11 Apr
        • Re: FAQ vs ManualIsabelle Poueriet18 Apr
  • Re: FAQ vs ManualEd Carp11 Apr
    • Re: FAQ vs ManualPaul DuBois11 Apr
    • Re: FAQ vs Manualjonathan michaels12 Apr
      • Re: FAQ vs ManualPaul DuBois12 Apr
  • Re: FAQ vs ManualEd Carp11 Apr
  • Re: FAQ vs ManualEd Carp12 Apr
    • Re: FAQ vs ManualIsabelle Poueriet18 Apr
  • Re: FAQ vs ManualFred Read12 Apr
    • Re: FAQ vs Manualjonathan michaels13 Apr
  • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Fred Read12 Apr
    • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Isabelle Poueriet18 Apr
  • Re: FAQ vs ManualRichard Reina13 Apr
  • Re: FAQ vs ManualFred Read13 Apr
  • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Ed Carp13 Apr
    • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Vivek Khera14 Apr
  • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Fred Read13 Apr
    • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Micheal Mc Evoy13 Apr
  • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Ed Carp13 Apr
  • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Ed Carp14 Apr
    • Re: FAQ vs Manual (was: Re: Creating a SQL script...)jonathan michaels15 Apr
      • Re: FAQ vs Manual (was: Re: Creating a SQL script...)Darrell Shifflett15 Apr
Re: FAQ vs Manual (was: Re: Creating a SQL script...)Fred Lindberg12 Apr
  • More about my FAQ...S. Whitmore13 Apr
    • Re: More about my FAQ...Fred Read13 Apr
    • Re: More about my FAQ...Ed Carp13 Apr
Re: FAQ vs Manualluuk13 Apr