location of developer tutorials

[Matt Rogers]

On Monday 18 December 2006 20:22, Aaron J. Seigo wrote:
> hi...
>
> right now we have two places coding tutorials (aka "things more useful than
> api docs for learning how to use classes in kde libs") might be found:
>
>  - developer.kde.org
>  - api docs, due to examples being in header files
>
> there are benefits to each. for instance, we can automate tests for them
> being in api docs. however, i'd like to suggest that we move these efforts
> to the new developer wiki. why? because:
>
>  - 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
>
> this latter point is perhaps the most important one, followed by the first
> point. why? because we really ought to give people *one* place from which
> to find all their learning aids for kde development. the "go here, and then
> over there, and the there's something over yonder" method just sucks. we
> also need to lower the barrier as much as possible: the fact that examples
> in api docu often end up outdated speaks loudly.
>
> i do realize that if we put all this stuff on the wiki we'll need to work
> on organization of it all. i've committed one day a week to this effort
> from now through at least the end of january and there are others putting
> in large amounts of effort such as danimo and dhaumann. i think we can do
> this.
>

What are the coordination points for all of this work?

> but of course we need some consensus and common direction here so we're not
> working at odds with each other. i may be completely missing some really
> important points in favour of tutorials housed in header files or strongly
> against a wiki. that's why i'm bringing it up here.
>
> (p.s.: i'm also working with some of the bindings and scripting people to
> get that part of the tutorial space rockin'.)
>
> (p.p.s.: the reason this is so important is that this high-level
> documentation void we have is probably the #1 blocker for people getting
> involved with kde development right now. it's the one i hear consistently
> at event after event, in conversation after conversation. this is Really
> Important(tm))

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.

Thanks
--
Matt