developer wiki fridays

monday is my day for kdelibs adjustments, and now friday has become my day to help with the new kde developer wiki. sort of like bookends to my week. i'll be doing developer wiki fridays until at least the end of january. maybe longer, but we'll see.

what is this developer wiki i speak of? it's the replacement for the somewhat haphazzard developer.kde.org. the new approach is to use a wiki so everyone can participate. it's looking pretty good so far, as you can see for yourself.

however, there are challenges ahead.

centralizing our content

right now you can find developer documentation scattered across the internet on various servers. for instance, there's some really great content on the kde women tutorials page, there's some articles on ibm's developerworks site, while an article on how to get started with the ruby bindings is hidden under the ever descriptive "bindings" entry on the sidebar on developer.kde.org. there's also a large number of tutorials hosted on people's personal webservers.

sweeping all these altogether is no mean feat. perhaps we shouldn't even bother doing this with older content, due to the time it would take and dealing with other people's links and bookmarks to the content. it's a lot of work.

at the very least we need to make the wiki the natural and first choice of authors of future works.

porting old documentation

i spent some time today sorting out kde2, kde3 and kde4 appropriate tutorials on to different pages. right now the idea is to make kde4 the primary focus of the site while keeping the older materials around for reference but in their own area of the site. unfortunately, there's very very little high-level documentation for kde4. sure, we've got the usual great API documentation but that's not a good way for people to learn how to actually write kde applications. that's what tutorials are for.

there are numerous technologies that kde4 is inheriting from kde3. if you look at the page of kde3 tutorials and compare them with the kde4 tutorials you'll notice that there's a lot less content. and even the kde3 tutorial are hardly comprehensive. many of the kde3 tutorials simply need to be gone through and "ported" to kde4. some, such as the xmlgui tutorial, probably aren't worth spending energy on right now as liveui looks like it will take its place now that people are working on it again.

kde4 documentation

we also have lots of cool new technologies in kde4. several of them are already usable by application developers, such as solid and phonon. we need to get tutorials for these technologies, starting with the basic concepts (e.g. a survey of the classes in solid) with other tutorials covering more advanced or specific topics (e.g. "embedding videos with phonon")

of course, there's also the holes that exist in our current tutorials. for example, we have a good tutorial on kconfigxt, but nothing on using kconfig itself.

we need to start writing these texts. they don't have to be long or overly complicated. even a single page article helps, sometimes a lot.

other useful bits

of course, it's not all about documentation. there's an area for ISVs, for instance, that's mostly content-free at the moment and what is there is already a bit dated. i think there's work here for the kde promo team.

developer wiki fridays

wouldn't it be nice if we couldn't list all the tutorials on the main tutorial page but had to break them up into separate pages because there were so many? wouldn't it be nice if our high level documentation covered enough of kde that people could use that material to create lesson plans around it and teach kde development in classrooms? =) we can do it!

our developer documentation is an important pathway to getting new developers and supporting those that we have today.

if you'd like to join me on fridays working on this, hunt me down on irc so we can coordinate a bit and keep each other company. if you'd like to start writing content or porting older tutorials, please don't wait for friday ... start whenever you can =)

credit where credit is due

the new wiki was not my idea or the results of my efforts. daniel molkentin and dominik haumann have been pushing this forward with sys admin tasks being performed by dirk mueller and artwork coming from nuno pinheiro and luke parry. there are probably others who have dipped their fingers into the wiki sauce as well. they all deserve a big "thank you!" for getting this started. they also deserve our help in making this the success we all would like it to be.

p.s. a sysadmin.kde.org site with a similar approach that started with the content from the kde.org sysadmin area would be nice, too.