List:General Discussion« Previous MessageNext Message »
From:Paul DuBois Date:April 12 1999 3:39pm
Subject:Re: FAQ vs Manual
View as plain text  
At 2:25 AM -0500 4/12/99, jonathan michaels wrote:
>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.

Let's see.  The MySQL manual is 400 pages.  Interpreting "a
week and a bit" liberally to mean 14 days, that's more than 28
pages a day.  Perhaps you are a really prolific writer.  Me,
I find writing documentation more difficult than writing code,
and it's a struggle to produce at a rate of even a page a day,
by the time I go through editing and revision.

In other words: I find your assertion astounding.  And unbelievable.
You may not *like* the manual (which is your right), but to say
you could have written it in such a little time...


>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

This is interesting.  You anticiplate a response to your message,
but phrase it in terms of an attack.  This indicates to me that
you feel perfectly free to offer criticism of the existing
documentation (and of course, you *are* perfectly free to do so),
but feel that if anyone offers criticism of your ideas in reply,
that's an attack.

Sorry.  If you want to participate in a discussion, then participate
in a discussion.  It is not credible to put your ideas out and
expect them not to be subject to critique.

>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.

This paragraph reveals that you have barely read the documentation
you so readily criticize.



>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.

This is little more than a (slightly)-veiled insult and it's
probably not going to get you very far on this list.  Anyway, does it
have some sort of relevance?

>
>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.

In other words: you will never do it, because you have your
physical disability to fall back on as an excuse.  I'm sorry
about your neurological disorder and dyslexia.  I'm sure these
make it quite difficult to work.  At the same time, they lead
to a technical point I must raise:  If you are going to introduce
into the documentation spelling and punctuation errors at the rate
that you do in your mail messages, this is going to be a significant
cause for concern.  I realize mailing list traffic isn't the same
thing as finished prose, but your postings don't really raise
my confidence in your ability to deliver.  And, sorry to say,
raising the problem of a disability doesn't cut it.

>
>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.

Okay.  But you offer no specific criticisms, and you offer no
specifics on how you would do things better.  What should we
make of this sweeping generalization?

>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.

Yow.  That's quite a paragraph.
1) What is "real document preparation," exactly?
2) WAIS?  I guess I'm missing something significant here.  Does
*anyone* use WAIS anymore?
3) re: noses out of joint - you have an odd way of wanting to
contribute to MySQL: write in such a way as to alienate the existing
community, and claim you can reinvent what's been done so far, but
better.


Sorry for the long message.  But you will need to be more specific
with your criticisms as well as what you will do better, and you'll
need to produce something other than mail messages.


--
Paul DuBois, paul@stripped
Northern League Chronicles: http://www.snake.net/nl/
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