techbase works

from the comments section on the dig page for the "techbase hits 1,000,000" story:

"I looked for this kind of information on their site some time ago and couldn't find it as organized and to the level of detail I needed (intermediate) and couldn't find it. I ended diving into source code, figured out some things, but couldn't get anywhere useful and I abandoned the project. Starting for your link, in 5 minutes I found the exact class and methods I was looking for." - SeattleGaucho

the power of documentation is amazing.

techbase hits one million

it took half a year to hit our first million, how much before it serves up its second million? it certainly shows that techbase is getting used and is an increasingly important part of our infrastructure.

in celebration of this event, i've started a trilogy of tutorials on kservice and plugins. we even have a plasma applet tutorial up now (not thanks to me, however =). i encourage every kde contributor to write a tutorial over the next few weeks covering a topic you know decently (you don't have to be an expert on it!) that isn't yet up on techbase. we're at 80 tutorials on techbase, let's push that number higher!

games; french techbase; italy; plasma

sleep, the final frontier.

somehow that's how it feels. i got less than 4 hours of it last night before my body decided it had had enough of that and wanted to go again. this happens in the spring and summer to me a lot, especially when the transition from winter first gets underway.

so up at 4am i did a little bit of irc'ing and then a little hacking and then realized that i had to be up in 3 hours anyways to get p. off to school so just stayed up. made breakfast for him, packed his lunch, walked him to school, came home, hacked a bit more and dealt with email. then came the meetings.

we had a plasma meeting today where we covered off on the artwork. the oxygen artists were cool enough to show up and give us some thoughts and direction. the hope is that in short order here we will have some non-fugly, non-whipped-up-in-10-minutes-for-testing-purposes svg's so that when people demo plasma it makes a really good first impression. we know that the art and layout of plasma will be our first impression moment for kde4, and are taking it pretty seriously due to that.

we talked about packaging options so people can ship custom themes easily, which led to a discussion later in the day with both kde-edu and kde-games people who are dealing with similar things. the result is that we're having an add ons and GetHotNewStuff2 BoF at aKademy to nail down the details. huzzah. it also resulted in me doing a bit of hacking on the GHNS2 download dialog, which led to me adding half a dozen TODOs for the API of KTitleWidget as well as the GHNS2 download dialog.

i also unfugged the file dialog's layout yesterday because it was really starting to cheese me off. there are still some issues with the side bar, but that's a new widget and still a work in progress (go kevin and peter!) and doesn't look too bad even now. kde4 has actually becoming a very comfortable development environment, both from the api standpoint as well the "a lot of components work and look decent now". and the latter bit is improving every day. anyways, i ramble... back to the plasma meeting.

we also discussed priorities and needs for data engines and documentation as well as how to handle saving applet configuration. a summary was posted to panel-devel and irc logs made available. and speaking of dataengines, i saw the first screenshot of the weather dataengine in action in the engine explorer today. whee!

i also found a cool little game in playground called kollision. in it you are a little ball and you have to move it around to avoid the nasty red balls that are bouncing around trying to run into you. it's a cute little fun game; best part: it's now a plasmoid. we haven't even finished, let alone released, plasma and already people are writing add ons for it. slick.

from the plasma meeting is was to a quick lunch and then the kde italia meeting on irc. upshot of that meeting is a coordinated effort in Italy by the kde people in that country to really kick up the promo, news and support in Italy. a mailing list is being launched along with a new wiki and a blog planet, both having content in the Italian language. it's just the start towards bigger goals, but you have to start somewhere and usually that's with creating a place for community to gather and share. it also gives the opportunity to get to know each other and figure out working relationships. go kde italia! =)

over in france, thanks to the efforts of our very own kde edu mastermind annma, techbase articles are starting to appear in french. annma gave a kde4 presentation that evidently made a big impression on the audience, so much so in fat that some of the people who were there have started the french techbase effort. that is awesome! we now have articles in english, chinese and french. getting documentation into various languages is a very important step towards lowering the bar to involvement.

to finish the day out, before making dinner for p. and i, i finished implementing the applet constraints system so now applets can adjust their form factor, orientation, etc. i'm going to make a screencast with audio tomorrow showing this off. =)

but right now, i'm off to bed. i feel tired and am going to take advantage of that. *kisses*

techbase updates

techbase continues to roll along as well. but as always: we need more content!

i added a bunch of explanatory text to the building kde4 tutorial and condensed some of the initial setting-things-up bits a bit. there was some action on the qt-dom tutorial and a number of nice edits here and there.

the development page needs to be reworked so it looks more like the front page, e.g. a pretty list instead of a blocky table.

danimo installed an image map mediawiki extension so that i can hook up the pretty picture pinheiro did for the isv section.

my contribution this week to tutorials will be on plugins using kservice, kservicetypetrader and kgenericfactory in combination.

why api documentation is good but not enough

accurately and thoroughly documenting our application programmer interfaces is absolutely critical to making the work we do in libraries and other components useful to other developers (including those who will take over for us in the future). however, as important as api docs are, it isn't enough.

api documentation is like labelling each piece of a larger machine: each screw, bolt, assembly tool, pipe, driveshaft, etc... one may be able to read all of these labels and after examining enough of the other pieces be able to figure out how to assemble the individual bits and pieces into a functioning whole. but one is just as likely not to be able to because there isn't a "big picture" goals provided to work towards and when there are hundreds or thousands of pieces it can be not only time consuming but very mentally taxing to assemble those bits in your head.

this is why we need what i call "high level" documentation: articles that cover in a narrative fashion how to use our technologies. these articles (or tutorials, HOWTOs, whatever you prefer) lead the reader along a path to specific end goals. rather than being comprehensive descriptions of the individual pieces (that's what api docs are for) they help the reader get the bigger picture: the final machine rather than the parts.

this makes the api documentation so much more understandable as the reader will now have a frame of reference to apply to the detailed information. it also makes the api documentation reference material rather than source material for learning, which allows us to write it as such and not try and stuff tutorials into our header files.

and why not put these tutorials in the api documentation? after all, we do have the ability to include mainpage.dox files and general sections in headers. the reason is quite simple: it's not easy to do things like provide references to images or other media from these pages, they aren't community editable (which means, in my experience, that they become static documents and bit rot faster than they should) and there are simply some topics which don't belong in any header file.

for instance, the intro to d-bus article i added today: which header file in kdelibs should that go in? or how about information that ties together multiple disparate technologies? this means that at least some of our high level documentation will live in one place, such as the developer wiki, and some of it will be in our api documentation.

spreading our information around like that simply makes it harder than necessary for those researching kde technology to get all their information. the obvious answer is to keep it all in one, community editable place.

and so i make the case that api documentation is vital and critical, that it needs to be augmented with high level tutorials and that the high level documentation should all be placed on the developer wiki. if you are providing a key and/or useful technology for kde4 and you haven't thought about providing this high level documentation, should the project really be shipping that work? personally i don't think so. just as we have complete api documentation coverage as a goal and requirement for public api's, i believe we should have high level documentation for all libraries/technologies in kde as a goal for the kde4 series.

and that is precisely what the developer wiki is attempting to provide. please, do your part in this effort. i know i've been harping on about this for the last few months, but i'm a pain like that: i'll keep on about it until someone either shows me that it isn't needed or until the developer wiki is full of nice articles on the pillars of kde4 from a developer's point of view.

ok, rant over. discuss. =)

d-bus tutorials; guademy

today i uploaded a first draft of an "introduction to d-bus" article on the developer wiki. this completes the cycle of four articles i promised i'd write to document d-bus from a qt/kde developer's point of view.

they are certainly not "final draft" worthy, however. while i did use proper capitalization ;) they are littered with my usual nasty combination of misspellings and odd grammatical practices. it would be most welcome if people would take a gander at the articles and work them over. in the process you could even let me know (via comments on the discussion page for each article) if they are clear enough or if there are things missing, wrong, etc... i'd greatly appreciate the feedback =)

it also appears that i'm going to guademy, which is a combined kde and gnome 3-day hackfest that is being held in spain. trolltech wanted to send someone to it and they picked me. it so happens that i was already heading to norway to speak at an event put on by the norwegian unix users group in kristiansand so was, relatively speaking, "in the neighbourhood". instead of going straight to norway, i'll be stopping off in a coruna first for a few days of free software desktop loving.

if you're going to guademy or are just in the a coruna area and want to hook up for a visit, let me know and we'll see what can be done.

i do have a bit of a hesitation over the whole thing as it means that many more flights and my last trip to spain resulted in nutritional challenges for me: i don't speak spanish (making negotiating in restaurants pretty much impossible) and i don't eat animals (spanish cuisine seems pretty heavy on the animal products). but who knows, maybe it'll work out better for my poor little stomach this time around =) i am looking forward to seeing the atlantic coast of spain, though =)