MAY
10
2004

Improving the developer experience

Collection of ideas on how to encourage more developers to develop with KDE.

I have been doing developer support on mailinglists, newsgroups and web forums for about three years now.
Support means helping developers solving development problems, especially for developers who are new
to Linux, Qt or KDE.

Helping developers new to KDE is quite difficult, because a lot of our advanced stuff is not so easy to
understand if you haven't already used it.

I put together some of my thoughts on how to improve the experience when developing KDE, any
kind of feedback appreciated.

I. Enhance lib API documentation

- Linking related classes
Provide links in the API docs between classes the usually work together, for example
between kde:KLibFactory and kde:KTrader. (btw. I can't find KTrader in the API docs for 3.2 or CVS,
for 3.1 it is under kio)

- Add information about which libs are needed (giving build system variables when appropriate)

- Add more source snippets
I think this could be a job for people starting with KDE related development, as they have to
make themselves comfortable with the KDE API anyway.
Important would be a recipe how to sumbit such snippets, so that they get reviewed by
developers who know those parts of the libraries very well.

For example it might be a working solution to load the standard icon for "File Open" and
put it in a kde:KAction, while the correct solution would be to use KStdAction:: open().

A secondary thought on namespaces, I think there should be a link or at least a hint on
the API entrance page, like there is one for classes in parenthese after the library name.

- Add links to examples (like in Qt docs)
Providing buildable examples for review by experienced developers might also be a nice
job for beginners interested in contributing.
Some areas definitely need help from experienced developers, stuff like IO jobs and
components.

- Improve visibility of generic solutions (Trader, Interfaces)
KDE's strength is great modularisation (KParts, plugins, Interfaces) but IIRC most
documentation discusses general KPart handling, no example that shows how easy it is
to embed a media playerusing KMediaPlayer:: Player

II. Add application API docs

- Add docs for plugin APIs, especially KHTML, Konqueror, Kicker

- Generate DCOP docs from headers like API docs, so there is a place to
look for explainations if you just found out there is are soe notify methods
in KNotify's default interface, but you have no idea what the parameter mean.

- See power users as high level developers
Creation of service menus, scripting with DCOP, scripting with commandline tools like kfmclient, kdialog).
Current documentation is mostly targeted at application developers using C++ (with some nice exceptions like Aaron's service menu tutorial)

III. Internal documentation

Make internal docs (Job metadata, XML GUI, ...) more visible
(linking from API docs, create a section on developer.kde.org for them)

You can find quite some threads on kde-devel where some developer has a question
about KDE specific feature like KIO jobs or XML GUI stuff, where medium level
developers like myself can't reach a point when they can't help any further, but the
next code developer that turns up just has to point to kdelibs/.../DESIGN which
explains everything relevant.

IV. Improve reachability of core developers

Developers with in-depth knowledge of KDE are sometimes hard to reach, usually because
they are not subscribed to the help areas, due to the high traffic and bad signal/noise ratio.
Maybe we can find a way to keep trivial questions away from them while bringing
difficult problems to their attention.

One idea is taken from KDE quality (or at least I understood some of the proposals this way):
provide a mediator layer, kind of human filters, which process the incoming traffic and
forward advanced problems to a restricted list, properly categorised, e.g. using a
subject prefix indicating the problems nature.

V. Improve KDevelop knowlegde

- Beginners and switchers from other platforms tend to use IDEs, sometimes they can't even
separate KDE and KDevelop ("how can xyz be done with KDevelop" while actually meaning
"how can xyz be done with Qt/KDE").

- Long term, experienced KDE developers, including myself, often don't use KDevelop (e.g. I use Kate) and thus can't
give instructions on how to apply solution in KDevelop, especially in build system
(how does one do the suggested Makefile.am modifaction using the automake manager),
installation (how do I tell KDevelop where to install data files/images)
or testing related problems (why do I have to "make install" just for testing and is
there another possibility)

VI. Integrate integrators or "KDE as a platform"

- Gather feedback from developers who try to integrate their applications with KDE
(scribus, OpenOffice.org integrator, Gambas developer, binding developers).
What do they find difficult, what would they like to have to make their live easier.
For example how do they detect location of KDE's headers, kde-config only can tell
the install path for libs.

- Provide runtime access to KDE: detect if KDE is running, which version, etc.

Maybe provide commandline client like kfmclient to access KDE configuration, for
general information like current language, double click policy, etc.

- Acknowledge integrators' efforts by displaying their work in the kde.org website
family. Maybe provide some official logo to tell visitors to their websites that
a KDE enhanced version is available.

- Advertise KDE as a platform
IMHO current developer mindshare sees KDE as some kind of Qt extension.
My pet example are frameworks that have platform dependend implementations like
wxWidgets or SWT.
IMHO there is no point in creating wxQt ot SWT/Qt as they already have implementations
on Qt's other platforms, but wxKDE or SWT/KDE would be nice additions.

- Especially encourage Qt developers to provide KDE enhancements, for example having a list
of necessary changes which would be needed to access certain KDE features
("When does a program need a KApplication instance, when is a KInstance instance
sufficient, etc).

Maybe offer some public domain code snippets with proper #ifdef'ed code
for example for creation and initialisation of the (Q/K)Application instance.

- Provide help for switchers (developers with experience on other platforms
e.g. Win32/MFC), possibly using first hand experience of KDE developers with
similar background.

VII. Tools

Encourage creation of tool programs, for example creating XML GUI file from .ui file
of a designer generated QMainWindow form.
It is like the IDE thing, beginners and switchers like tools, even for things we
consider trivial.
Creation of helper tools might actually be nice jobs for those beginners.

Comments

... was for an API docs system like PHP.net has. Most of the time the notes at the bottom of the docs are more useful than the docs themselves. I wonder how hard that would be to integrate with Doxygen generated docs.


By Ian Reinhart Geiser at Tue, 05/11/2004 - 03:18

Seriously, that's one of the best ideas I've ever heard.

PHP was easy to learn because of all of the example code snippets attached to all of the function documentation.

If we had this for KDE....


By KDE User at Sun, 05/23/2004 - 03:38

You have some really good points here. Especially "I. Enhance lib API documentation" and "III. Internal documentation" would be really helpful even for more advanced KDE developers.

I think especially the short code snippets in the class description part are often very helpful (see Qt docs), but we don't have enough of them in our API docs. I guess this would be easy to fix when every developer (me included) would spend some time on this.

Also what I always wanted to do is to add tooltips to kdcop that show the doxygen API documentation when you hover over a method. I guess I should get out my old flex/yacc book and take a look at dcopidl again. :-)


By Christian Loose at Tue, 05/11/2004 - 08:49

... Test Driven Development is the best way to go. You ALWAYS have code snippets, YOUR TESTS! To artificially come up with contrived examples will always lead to ambiguous useless examples that don't show off what the method/class really does. A unit test shows exactly what the author intended and how the method/class is setup, used and torn down correctly....

just my 2c though ;)


By Ian Reinhart Geiser at Tue, 05/11/2004 - 13:45

And i always thought Test Driven Development is to come up with artificially contrived code examples. ;-)

Now to be serious a code example (unit test) similar to the complete examples in the Qt docs provide would be of course great, but I still think that even a small code snippet that shows the general usage of the class would be enough already (at least most of the times).

See http://api.kde.org/cvs-api/kdecore/html/classKAboutData.html for an example. A code snippet like the following would IMHO help to understand this class (not that it's hard to understand):

    KAboutData about("khello", I18N_NOOP("KHello"), "0.1",
                     I18N_NOOP("A KDE version of Hello, world!"),
                     KAboutData::License_LGPL,
                     I18N_NOOP("Copyright (c) 2003 Developer"));

    about.addAuthor("Joe Developer", I18N_NOOP("developer"), "[email protected]", 0);

    about.addCredit("Joe User", I18N_NOOP("A lot of bug reports"),
                    "[email protected]", 0);

    KCmdLineArgs::init(argc, argv, &about);

By Christian Loose at Tue, 05/11/2004 - 15:38

    And i always thought Test Driven Development is to come up with artificially contrived code examples.

That hints that you stepped into unit testing from the wrong direction. If you use unit testing as a way to define your API instead of testing the API this problem does not happen.

The point of unit testing is to write your testing code (using the API you want to test) first, and writing the implementation of that API later. This leads to the strategy that a test defines the API with the most simple use cases available.

I tell my collegues that they should either write APIdocs, or write UnitTests. As the end result is the same.


By Thomas Zander at Sun, 05/16/2004 - 09:13

I tell my collegues that they should either write APIdocs, or write UnitTests. As the end result is the same.

I'd argue that they should do both ;)


By tjansen at Sun, 05/16/2004 - 14:55

I'd like to have some input of the core devs how to handle adding of snippets or preparing examples, so we can ensure the correctness and quality.

For example if I want to add a snippet showing how to use KTrader to load a KMediPlayer::Player implementor, should I add it to the header file right away or should I post a patch for review?
If latter, where to?

Btw, anyone have an example on how KDirLister and KFileView are supposed to be connected together?

Also what I always wanted to do is to add tooltips to kdcop that show the doxygen API documentation when you hover over a method. I guess I should get out my old flex/yacc book and take a look at dcopidl again.
That would be awesome!

As a base docu we would still need application's DCOP interfaces online somewhere.
Do you think it would be a bad idea to include it in the user documentation of the respective application as well?


By krake at Wed, 05/12/2004 - 16:13

YOU ARE RIGHT !

QT Documentaion is so easy to browse / read.
It's easy and also efficient / quick to have a new concept.

KDE documentation is empty the most time (how much have we encountered one undocumented classe that we don't know what it is... with just methods names or classes goodly documented... exept the function that seem to some the problem we have :-/ ).

It's also hard to move from QT to KDE.
We don't know what to do, what are the benefits of KDE classes...

Currently, I search to have a good toolbar, KDE powered.
I don't know how to do it.
I always hard code things because I don't want to take time to search hard.
KConfigXT, KParts, KXMLGUI (must I really use it or always hard code KActions...).

The last example I remember is for global shortcuts hotkeys.
I've took a long browsing a lot of quit same classes (it was as incomprehensible as do a Java GUI : lot and lot of classes, without examples... We should guess the code). Just after seeing the code of a KDE program I was surprised that it take only few lines and not so difficult and classes are not so numerous...

Bref :
1/ Have good documentations and avoid docs like "void foo() : does foo void bar() : does bar). Have more deep explains and ALWAYS explain what do classes and methods !
2/ Provide examples (short ones, perhapse links to KDE WebCVS of programs that use that : the keyword is LINK : perhapse doc exists but we should browse long time for just a smmall feature)
3/ There are tutorials on the WEB. One time more : need links.

On other hands, as you have said it, provide more infos for scripts.
And more tools also.
Like a cli program to display KPassivePopups (I think I will develop it)... KPrint that print direclty in PDF or PostScript without showing dialogs...

And KDevelop should be extended as well !
It arrives that I add files to it and it isn't took in account, or a project setting isn't applied... I've insulted a long time for that stupidity. NOW I quite know basically what each make**** does and know what command to manually launch or the order I should configure/make in the Build menu... But it's unneeded : it should do that automatically !

Just an offtopic bracket : why do some use e.g. Kate instead of KDevelop ?
In KDevelop a F9 key press compile and then execute program.
It's so easy and fast !
Also Ctrl+J and Ctrl+Space to show corresponding methods/variables !
It add lot of speed !

Integrate QTDesigner would also be more good (forsee in QT 4.0).
In Glade we can add "standard buttons" with GNOME pixmaps.
I would want to add KStdActions directly in QT Designer and work on a XMLGUI transparently (no need to edit MakeFiles, config files, compile etc...)
BUT also integrate various technologies like XMLGUI, KConfigXT, DCOP, etc...
Actually those parts are framented all arround the WEB.
We need to show the power of KDE in a very short time to developers (and users also).

To conclue my long post and go to your way :
KDE is VERY powerful and has lot of interesting technologies.
But it's the same as Mozilla framework : it's quite "hidden" and difficult to reach quickly !


By sebien at Tue, 05/11/2004 - 18:54

KDE documentation is empty the most time

Since we adopted the Library Documentation Policy ( http://developer.kde.org/policies/documentationpolicy.html ) the situation improved a lot. If you still find a class without any documentation, send a mail to kde-devel mailing list. I'm sure someone will take care of it.


I always hard code things because I don’t want to take time to search hard.
KConfigXT, KParts, KXMLGUI (must I really use it or always hard code KActions…).

http://developer.kde.org is a good starting point here. Especially the tutorial page ( http://developer.kde.org/documentation/tutorials/index.html ) already contains some good stuff, e.g.

KConfigXT -> http://developer.kde.org/documentation/tutorials/kconfigxt/kconfigxt.html

Like a cli program to display KPassivePopups (I think I will develop it)

Too late. :-) KDialog will offer this with KDE 3.3.

Bye
Christian


By Christian Loose at Tue, 05/11/2004 - 22:33

Pages