location of developer tutorials

[Cornelius Schumacher]

On Tuesday 19 December 2006 03:22, Aaron J. Seigo wrote:
>
>  - 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

I agree that these are good reasons to have the tutorials in the Wiki instead 
of in header files.

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.

How would we get compiled code into the Wiki? 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.

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.

-- 
Cornelius Schumacher <schumacher at kde.org>