location of developer tutorials

[Aaron J. Seigo]

hi...

right now we have two places coding tutorials (aka "things more useful than 
api docs for learning how to use classes in kde libs") might be found:

 - developer.kde.org
 - api docs, due to examples being in header files

there are benefits to each. for instance, we can automate tests for them being 
in api docs. however, i'd like to suggest that we move these efforts to the 
new developer wiki. why? because:

 - the wiki is communally editable. this means even those w/out an svn account 
can help us out and it's easier than "edit a file, build api docu, see the 
results". extra bonus points for not having to recompile large chunks of code 
after making these changes (i'll bet that's why TT puts their docu in 
the .cpp files ;)
 - it's easier (at least to me ;) to reference images and do nice mark up in 
the wiki
 - the wiki looks more beautiful
 - there are some tutorials that don't have a nice home in a header file that 
gets process into api docu, but any example in api docu could be housed on 
the wiki

this latter point is perhaps the most important one, followed by the first 
point. why? because we really ought to give people *one* place from which to 
find all their learning aids for kde development. the "go here, and then over 
there, and the there's something over yonder" method just sucks. we also need 
to lower the barrier as much as possible: the fact that examples in api docu 
often end up outdated speaks loudly.

i do realize that if we put all this stuff on the wiki we'll need to work on 
organization of it all. i've committed one day a week to this effort from now 
through at least the end of january and there are others putting in large 
amounts of effort such as danimo and dhaumann. i think we can do this.

but of course we need some consensus and common direction here so we're not 
working at odds with each other. i may be completely missing some really 
important points in favour of tutorials housed in header files or strongly 
against a wiki. that's why i'm bringing it up here.

(p.s.: i'm also working with some of the bindings and scripting people to get 
that part of the tutorial space rockin'.)

(p.p.s.: the reason this is so important is that this high-level documentation 
void we have is probably the #1 blocker for people getting involved with kde 
development right now. it's the one i hear consistently at event after event, 
in conversation after conversation. this is Really Important(tm))

-- 
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

Full time KDE developer sponsored by Trolltech (http://www.trolltech.com)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20061218/50a8ac75/attachment.sig>