List:MySQL++« Previous MessageNext Message »
From:Steve Mansfield Date:March 7 2005 9:54pm
Subject:Re: Documentation
View as plain text  
-------------------
On Monday 07 March 2005 20:32, Warren Young wrote:
| Steve Mansfield wrote:
| > Indeed - as I go through the manual (which, on reflection, is really,
| > *really* awful) I'm having a lot of those 'huh?' moments. Trouble is, at
| > this stage I don't know whether those are caused by my lack of knowledge
| > about C++ or just obscurity in the manual itself.
|
| The problem isn't that the manual is obscure, it's that it's a reference
| manual, not a tutorial.  Sure, there's stuff in there that tries to be a
| tutorial, but they should be separated out and clarified.  We should
| either have two manuals, or at least a manual in two sections.  What a
| newbie wants from a manual is not the same thing that those of us who
| have been using MySQL++ for years want.

True, up to a point. The two problems with the manual (from a newbie 
perspective) are:

* It tries to inform by inference - in other words, it relies too heavily on 
showing a code example (which, of course, now differs wildly from the 
examples actually supplied) and then expecting one to devine what's going on 
from that.

* It's maddeningly random and partial in what it tells you.

Okay, an example or two:

I look at the early section on Result Sets where it attempts to describe the 
different types, but with no indication on how they differ in practical terms 
(ie, some idea of why you'd use one rather than the other) or what form these 
results sets take.

More specifically, the 'simple' example shows how to pull some rows from a 
table and print them. I managed to get this working without too much trouble, 
but then I look at the query object and see that it has a number of methods - 
query.store(), query.preview() and I immediately want to know what other 
methods there are, what types they return, what parameters, if any, they 
might take. In other words, a reference list of all the methods, properties, 
structures & types in the API would be very interesting. That way I can play 
around with them and learn by experience.

Now, you might argue that much of this info can be gleaned by sifting through 
the code, looking at function and class declarations etc. But that's the kind 
of effort a manual is meant to avoid.

I find the PHP manual very useful partly because I can browse it - I've 
discovered all manner of useful functions that I wouldn't have thought to 
search for that way. It tells you what each function does, what params it 
takes, what type it returns.

I guess what I'm saying is that I need Chapter 5! And obviously the manual 
needs to be brought up to date by using the actual code from the examples. 
Lots of commenting in the code might help, too.

Anyway, I'll see if I can come up with some sensible comments on the manual 
as-is.

-- 
@+
Steve
Thread
DocumentationJoachim Person6 Mar
  • Re: DocumentationEarl Miles6 Mar
    • Re: DocumentationSteve Mansfield6 Mar
      • Re: DocumentationWarren Young7 Mar
        • Re: DocumentationSteve Mansfield7 Mar
          • Re: DocumentationWarren Young7 Mar
            • Re: DocumentationChris Frey7 Mar
              • Re: DocumentationEarl Miles7 Mar
                • Re: DocumentationWarren Young9 Mar
            • Re: DocumentationSteve Mansfield7 Mar
              • Re: DocumentationEarl Miles7 Mar
                • Re: DocumentationSteve Mansfield8 Mar
          • Re: DocumentationChris Frey7 Mar