[DGD] Call for critique: LPC documentation

[Noah Gibbs]

--- John Ruiz <jruiz at johnruiz.com> wrote:
> Your newest installation seems geared for the
> very beginner - new to both
> DGD and LPC

  Yes and no.  What I'm doing with the new book,
honestly, is writing somethat that flows just like
"The C Programming Language" by Kernighan and Ritchie.
 That means it'll have a very substantial amount of
up-front tutorial, followed by in-depth sections
afterward by topic.  So if you want to know everything
about arrays, you won't turn to the tutorial section
on arrays -- you'll turn to the *chapter* on arrays. 
However, that chapter isn't written yet, and your
criticism is certainly correct if applied to only the
tutorial chapter.

  Also, bear in mind that this is a replacement for
the old textbook ("http://phantasmal.sf.net/DGD/LPC"),
not for my entire site, which is worth keeping in
mind.  The old textbook wasn't perfect for quick
reference either :-)

> This could be done through a lot
> of URLs over keywords or phrases (a.k.a popup
> boxes) which a beginner may
> need to have defined or explained a little
> further. 

  At the very least I should probably link to the
chapters on various topics as I cover them in the
tutorial.  I'm not doing that yet, but I haven't
written most of those chapters yet :-)

  I'll probably wind up doing an "index lite" later on
as well -- a table of links to the various tables in
the book so that you can get, say, operator precedence
or a list of function modifiers or data types quite
quickly.  I figure that most people's quick-reference
needs will be solved by a combination of that and a
good function reference, plus a reasonably
example-heavy chapter on each major language topic
(functions, arrays, mappings, LWOs, etc).

  I should probably set up 'stubs' for each of the
chapters...  Currently I expect most people will make
(what I perceive to be) your current mistake, and
believe that the tutorial chapter is basically
everything I'm planning to do.  I *do* consider the
tutorial to be the most immediately useful thing I'm
doing, simply because it's much shorter than the
'grand vision' for the book, and can become fully
useful correspondingly faster.

  Plus the existing tutorials all suck, while there's
already a halfway-usable quick reference out there :-)



=====
------
noah_gibbs at yahoo.com

__________________________________
Do you Yahoo!?
Yahoo! SiteBuilder - Free web site building tool. Try it!
http://webhosting.yahoo.com/ps/sb/
_________________________________________________________________
List config page:  http://list.imaginary.com/mailman/listinfo/dgd