Re: API Fragmentation and Cleanup

[Kenny Graunke <kenny whitecape org>]

On Friday 27 April 2001 04:19 pm, you wrote:
> hi kenny,
>
> I just spent 10 minutes writing a long answer but evolution's C-W
> shortcut (close composer window) killed my window (yes, in emacs, it
> means, cut selection!!!). So, here is a shorter answer:

Oops. :(

> 1) Simple solution: redesign everything. Rewrite a new Gnome, reuse
> everywhere a set of weel defined design patterns, orthogonalize the
> API... Blah... Result: 2 years, 200 developpers, 80 managers, millions
> of dollars. even then, it will be difficult to get it right if you want
> to keep a minimum o interoperability with previous Gnome.

Right. I am certainly not advocating redesigning everything and rewriting 
GNOME from scratch. That would be completely inpractical.

> 2) more complicated solution: add new cleaned up APIs, deprecate old
> ones. Keep binary compatibility. Possible, long and error prone. the new
> APIs have to be fuckingly well designed and thought out.

True, but when moving between major releases (like 1.x, 2.x, and 3.x), it's 
generally OK to break source and binary compatibility, if it improves the 
framework...I certainly do not mean to break source or binary compatibility 
between minor releases (1.2, 1.4, ...)

> 3) the most complicated solution: WRITE GREAT DOCUMENTATION.
> This includes in the order of most important to least important:
>
>     - overall architectural introduction to the Gnome development
>     platform.
>     - overall architectural introduction to major parts of the
>     development platforms. This includes a quick tour of the code with
>     pointers to important source files.
>     - pointers to great API documentation.

Our developer documentation is in sad shape right now. Hopefully we can fix 
this, however, good documentation should not be seen as an excuse for 
fragmented or poor APIs - either it will just make sense or it will "make 
sense" after reading 500 pages of manuals describing it and making excuses 
for the mess.

Yes, we definately need to have good documentation. We also need to have a 
good API. I think these are both important, but neither can really replace 
the other.

> What I just described is basically a redesign of the Gnome developer
> documentation ? volunteers ? I volunteer myself to hack an outline of it
> for review by everyone to yell at me.

Thanks, Mathieu.

--Kenny