Re: GNUe documentation

On 10/24/06, Baurzhan Ismagulov <[email protected]> wrote:
> Hello James,
>
> On Tue, Oct 24, 2006 at 09:19:45AM -0500, James Thompson wrote:
> > I'm going to make an attempt at correcting our documentation problem.  Via
> > discussions in IRC we've tenatively decided on 2 main guides to the project.
> > A complete reference and a learning guide.  The first to be built will be the
> > complete reference which will then provide source material used to build a
> > learning guide.
> >
> > The plan is to.....
> >   develop a basic outline of the complete guide
> >   merge in all the existing tools documenation
> >   delete all the original docs after they are merged
> >   expand and complete the missing sections
> >
> > Below is a still incomplete stab at an outline for the complete guide.  I'd
> > appreciate any input or suggestions on extending or improving it.
>
> Although not quite an answer to your question, but may I suggest that
> you reverse the priorities? IMHO, the first thing people need is the
> learning guide.

I fully agree with the original plan:  to start with the complete manual and
integrate the existing guides into the suggested outline.  And delete the
old docs afterwards (i like this idea - it will avoid confusions).

As far as I understood, James'  intention is that the learning guide will
be a stripped down version of the complete guide. It would be easier for
the author to write the learning guide after the complete manual is done.
(please correct me if i'm wrong)

Or ...  the learning guide could be the part entitled "A Complete
Example" - a tutorial that describes step-by-step how to build a
complex application.

So, I wouldn't reverse any priorities .


> After we are familiar with the basics, we'll hopefully
> be able to find out many things on ourselves. At least this is the
> experience from other similar frameworks I've worked with.

Sorry, I don't agree. This would not bring truly significant improvements.

The concept of "finding out things yourself" is the current situation. No
manual is needed for that  ;-)

The basics aren't that difficult:  once you have managed to configure the
connections.conf  you can create some forms with the gnue-designer !

The next steps are the difficult part - and here is where the complete manual
is neccessary.

> The web site already covers what GNUe is, what tiers and which tools
> there are. What I personally would like to see is a really short but
> complete quick start guide.

A short and complete manual?  at the same time ?
This proposed quick start guide  implies some redundancy with the complete
one, and I'm not sure that there is enough manpower available.

What I'm looking forward to see first is the complete guide.  Sure, the first
draft would probably contain the existing guides re-organised in only one
document. This first step would be very useful, because there would be
only one definitive place to look instead of a bunch of multiple scattered
docs.


Cheers,
Adrian Maier