location of developer tutorials

[Aaron J. Seigo]

On Tuesday 19 December 2006 3:59, Cornelius Schumacher wrote:
> But one point I'm missing is how it is made sure that the code used in the
> tutorials is correct and actually works. The only way to guarantee this is
> to have the code used for tutorials as compiled examples, like e.g. the Qt
> tutorial does it.

this is a fine idea. someone would need to do the upkeep on the compiled 
examples, of course, but compile errors could be easily tracked with a 
tinderbox somewhere.

that said, is it bad to have tutorials for older versions of KDE? a tutorial 
might easily wish to show how to do it in kde x.y as well as x.++y

> How would we get compiled code into the Wiki? 

pointing to a repository somewhere? of course now we're back to "can't easily 
be editted" but the compile errors should help.

then again, we're seriously raising the bar of writing these things. remember, 
these tutorials aren't writing themselves, in fact *we're* not even writing 
them right now. i don't think making it harder to write a tutorial ("you also 
have to have a compiling program to go with it") is a good way to go.

look at the kconfigxt tutorial. it's not comprehensive, but it's a good 
introduction. note the lack of a compiled app. think of the additional work 
that would have been involved to create such an app.

i really think this would make it much harder to get people to contribute.

> Keeping the content of the 
> Wiki up-to-date and in sync with the code manually would be one option, but
> probably not one leading to quality results. When the code would be part of
> the API docs, tutorials could probably be extracted from working source
> code as extracting things from source is done by the API docs generation
> tools anyway.

a) API docs are not tutorials.
b) have you seen some of the examples in the headers? they often fall out of 
date. so you'd have to extract the example, extract the code therein, build 
that, note problems and get someone with svn access to edit it ..... and with 
all the drawbacks of it not being communally editable and coming with an 
additional time related price tag (e.g. recompiles)

coupling high level documentation with software development release cycles is 
also a bit mind boggling. "oh, yeah, you'll get the new version of that 
example when kde 4.0.2 is released next month."

> But it could also be something separate, for example tutorials could be
> written as C++ programs with the tutorial text embedded in comments or
> something like that and then a script could create beautiful web pages from
> that. That's more effort short-term, but would probably pay off in the long
> term.

no, it wouldn't. it would lead us directly back to where we are:

a non-easily editted set of documents with varying look and feel that would 
require post-processing only some of us can or will do that aren't really 
optimized for humans but for compilers and code processing tools.

-- 
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/20061219/081008bc/attachment.sig>