location of developer tutorials

Aaron J. Seigo aseigo at kde.org
Tue Dec 19 12:58:02 GMT 2006


On Tuesday 19 December 2006 4:18, Jos van den Oever wrote:
> This is a good point. Generating tutorials from buildable code makes a
> lot of sense. 

on paper, maybe. but as soon as one wants to actually teach people with it 
you'll find that an effective teaching text doesn't flow nicely from comments 
interspersed with code. not to mention there's no guarantee the 
comments-which-are-actually-an-article reflect the code as it gets changed 
unless one spends a lot of due diligence on it.

> 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.

tutorials are not and should not be unit tests. they are learning materials 
that should be written with teaching specific aspects of things to people. 
unit tests are meant to rigorously test code paths.

> Since unit tests 
> specify how code should behave, they could also form a valuable part
> of documentation.

this i agree with, but we're on to a slightly different documentation topic 
with this =)

-- 
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/2926f9a6/attachment.sig>


More information about the kde-core-devel mailing list