location of developer tutorials

[Cornelius Schumacher]

On Tuesday 19 December 2006 14:07, Aaron J. Seigo wrote:
>
> that said, is it bad to have tutorials for older versions of KDE? a
> tutorial might easily wish to show how to do it in kde x.y as well as x.++y

It's of course not bad to have tutorials for older versions of KDE, and I 
think we should support writing applications against some older versions of 
KDE as much as we can.

But it would be bad to have tutorials which don't work with the latest stable 
release of KDE. We can gain a lot of trust in our developer documentation, if 
it is exact and actually works.

> then again, we're seriously raising the bar of writing these things.
> remember, these tutorials aren't writing themselves, in fact *we're* not
> even writing them right now. i don't think making it harder to write a
> tutorial ("you also have to have a compiling program to go with it") is a
> good way to go.

I'm not proposing to make this a requirement. I'm perfectly fine with 
tutorials which don't come with compilable code. But for those which come 
with code which is meant to work as an example we have to make sure that this 
expectation is met and the easiest way is to use the infrastructure we have 
and actually compile it.

> look at the kconfigxt tutorial. it's not comprehensive, but it's a good
> introduction. note the lack of a compiled app. think of the additional work
> that would have been involved to create such an app.

As said before, I think that's perfectly fine and we should encourage to write 
this kind of tutorials and a Wiki might be the right place for that.

> i really think this would make it much harder to get people to contribute.

We have a lot of people which are very comfortable with writing code. If we 
can encourage them to write tutorials by making use of what they can do best 
we can probably benefit. That's only one way of contributing to developer 
documentation. There are other ways and we should make the barrier as low as 
possible.

> coupling high level documentation with software development release cycles
> is also a bit mind boggling. "oh, yeah, you'll get the new version of that
> example when kde 4.0.2 is released next month."

Documentation always is coupled with software release cycles as it has to 
adapt to changes in the APIs. This doesn't mean that it should be done in a 
way which doesn't allow to improve developer documentation without releasing 
software. Having documentation which doesn't work with the current version of 
the API is kind of embarrassing, though. As we are much better in maintaining 
code than developer documentation, I'm proposing to provide a way to make 
maintaining developer documentation similar to making code. I'm not certain 
if this will work out, but having this option might be an interesting 
alternative, so we shouldn't exclude this right away.

> no, it wouldn't. it would lead us directly back to where we are:
>
> a non-easily editted set of documents with varying look and feel that would
> require post-processing only some of us can or will do that aren't really
> optimized for humans but for compilers and code processing tools.

Well, developers are in some way "code processing" people. From my experience 
it's very valuable to have a working example which can be used by copy and 
paste, in many cases much more valuable than a prettily formatted example 
which isn't entirely correct.

That said I'm not opposing documentation optimized for humans. But I think 
documentation optimized for use with compilers will also help us to provide 
what developers need to write great KDE software. It's not an exclusive 
thing, both ways will supplement each other.

-- 
Cornelius Schumacher <schumacher at kde.org>