location of developer tutorials

[Aaron J. Seigo]

On Tuesday 19 December 2006 4:02, Adriaan de Groot wrote:
> This is a tough call. A tutorial's aim is to teach people how to use some
> piece of technology and includes an introduction to the process. It does
> some handholding. It explains the how and why of things. How to do things
> right and why to do them right in the context of a whole (probably a
> complete program) that demonstrates the technology.
>
> An example (in the APIDOX) is short and shows how to use a technology for a
> specific effect or to solve a specific problem. It does not show nearly as
> much context and is less of a storyline.

that's what they should be, yes. i've seen some examples from phonon that are 
going in quite a different direction (e.g. kdelibs/phonon/backend.dox). it's 
a valuable effort and very useful except that it's in kdelibs/phonon/ in a 
format that's pretty opaque to most people and not easily edited.

remember how wikipedia apparently works: a few people contribute large amounts 
of content, tons of people spend time polishing it up.

how does a user of phonon that ran into an issue glossed over in *dox improve 
it? at best, they email mkretz with some text with the hopes he'll merge it 
and commit it and one day it'll be available to them when the docs are 
regenerated.

or take a look at the example in KCmdLineArgs. really nice bit, except it 
lacks a lot of actually useful detail, probably to keep it from becoming too 
long. it's a bit more than a "how to use the class" but a bit less than a 
full tutorial. i mean, there's even tips for end users in there! heh. imho it 
should really just cover how to use the class in a terse "this is not a book" 
way and then point to a tutorial somewhere else for thorough coverage of it. 
this is what you'll see in the Qt docs, for instance.

so these are the kinds of cases i'm thinking about when i say, "we should 
think about, and set some policy, as to where these kinds of tutorial 
materials go."

> Tutorials *can* be in the APIDOX (Write a Tutorial.dox file, for instance),
> but probably need so much supporting (multimedia) content that it is
> impractical to have them in the source tree.

... and not easily editable, etc, etc...

> Examples *should* be in the APIDOX for all classes showing how to use the
> class.

let's just keep them to examples: succinct, to the point and technical.

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