Re: [GNUe] GNUe documentation

[Baurzhan Ismagulov]

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.

This is a great news! The complete guide is going to be a good source of
information on GNUe.

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

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, like this:

1. Introduction

   This document describes how to write your first two-tier GNUe address
   book.

   (That's all, I don't think we need anything else here).

2. Installation

   On Debian unstable, install the following packages:
   * gnue-appserver
   * gnue-common
   * gnue-designer
   * gnue-forms
   * gnue-reports

   (Choose one platform and list either source or binary packages we
   need to install. Don't describe how, platform users or yourself can
   easily contribute this later. This is a document about GNUe,
   concentrate on the next section).

3. Development

3.1 Configuration
3.2 Appserver
3.3 Forms
3.4 Reports
3.5 Navigator

4. Conclusion

   (Perhaps suggestions about execution or deployment).


I hope I expressed my wish clearly: Really short. Complete. Don't
overdo, you can always do that later :) in the complete guide. Cover the
essentials as quickly as possible in a complete document and release it.

The problem with some of the current guides is that they describe the
first two steps in great detail and cover the rest with TBD. We don't
need much, "just" a complete section 3. What do you think?


I'm looking forward to seeing the document!


Thanks in advance,
Baurzhan.