Re: How do I switch to Sawfish??

[James Henstridge <james daa com au>]

Ali Akcaagac wrote:

> the problem here is:
>
> a) there are NO gnome 2 conform programming tutorials. only the gnome 2
>   porting guide and a lot of outdated gnome 1 readme's.
> b) api reference manuals are not enough to program things. specially for
>   those that don't develop on gnome.
It would probably be a good idea to add overview/tutorial information to 
the beginning of reference manuals.  I have some documentation like this 
at the beginning of the libglade manual (granted, it probably needs a 
little more updating since the 2.0 release).  Like a lot of issues, 
people haven't had enough time to get good tutorials ready for gnome 2.0 
(I don't think waiting for all the docs to be updated would have been 
worth it either.  The gap between the 1.4 and 2.0 releases was already 
too long).

This area will improve, but it takes time (at the gnome 1.0 release, we 
didn't have the level of docs available at the 1.4 release either ...).

> the gnome 2 plattform would have been done good to release good library
> documentations for programmers too. so there could be real 3rd party
> apps. so basically getting the new libraries are only the half of what a
> developer needs. i mean if i read things like this (an example):
>
> GnomeVFSURI
The gtk-doc framework should be converting this into a hyperlink to the 
GnomeVFSURI documentation.  If it is not, then it is probably a bug in 
the documentation :)  Again, this sort of thing could be addressed by 
better overview chapters at the beginning of documents.

> then i don't get out much information. it opens and you need to unref
> things but there is no where mentioned what unrefing means in detail.
> having to read a lot of api and outdated stuff wich also contains
> 'FIXME: need to write chapter' doesn't help either. instead wasting the
> time writing useless stuff like HIG or GEP it would have been more
> important writing serious programming manuals with examples, with
> detailed explainations why it was done, how one should use it and what
> the purpose of things are.
The GEPs are not a waste at all.  Take a look at the Python PEPs for an 
example.  You get a good description of an upcomming feature, a 
discussion of the purpose of the feature and why you might want to use 
it, reasons why the solution was chosen over alternatives, etc.  When a 
new Python release comes out, they point to the PEPs as whitepapers.  It 
is very helpful to get a good understanding of what's new in the release 
without having to diff the reference manual :)

They also act as a starting point for detailed documentation of the 
feature.  I don't think it makes sense to criticise the use of GEPs 
until we see their effect on the 2.2 release process.

> and please belive me i read everything on d.g.o. if there wasnt these
> nice documentations from michael meeks about bonobo and howto do some
> basic things with it then i would probably be hopeless lost today.
>
> even the old motif documentation are full detailed describing everything
> etc.that is what i personally miss for gnome today.
It would be nice to get this level of documentation, and any help doing 
so would be appreciated.

> this should be a constructive criticism without any flame intentions.
>
>  

James.

--
Email: james daa com au              | Linux.conf.au   http://linux.conf.au/
WWW:   http://www.daa.com.au/~james/ | Jan 22-25   Perth, Western Australia.