location of developer tutorials

[Jos van den Oever]

2006/12/19, Cornelius Schumacher <schumacher at kde.org>:
> 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.
This is a good point. Generating tutorials from buildable code makes a
lot of sense. Using nice Doxygen CSS you can achieve a lot. Having
scripts which generate tutorial pages from code like could also be
used to make webpages describing the unit tests. Since unit tests
specify how code should behave, they could also form a valuable part
of documentation.

Cheers,
Jos