[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [GNUe] GNUe documentation
Re: [GNUe] GNUe documentation
Wed, 25 Oct 2006 11:17:06 +0300
On 10/24/06, Baurzhan Ismagulov <address@hidden> wrote:
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
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
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
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