location of developer tutorials

[Adriaan de Groot]

On Tuesday 19 December 2006 05:52, Aaron J. Seigo wrote:
> On Monday 18 December 2006 20:18, Matt Rogers wrote:
> > Will we still keep examples of when and how to use certain functions in
> > the API documentation? To me, that's important to have in both places
> > since part of the API documentation is to explain the when and why of
> > using things rather than provide concrete examples of usage.
>
> yes, i think this is perfect for API documentation: succinct summaries of
> the classes. but what i'm seeing in the API docu is more tutorial like work
> with paragraph after paragraph of explanation complete with examples, etc.

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.

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.

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

-- 
KDE Quality Team  http://www.englishbreakfastnetwork.org/
GPG: FEA2 A3FE    http://people.fruitsalad.org/adridg/