Aaron J. Seigo: Adding WhatsThis Help To KDE Applications

Adding WhatsThis Help To KDE Applications is the first installment in the Non-Programmer's Guide to Participating in KDE tutorial series. This series is designed to aid those who would like to participate in the KDE project, but for one reason or another can't do so by contributing source code. Fortunately, there are many tasks in KDE that don't involve writing code, and many of them don't require much investment in the way of time, either. Adding WhatsThis help in KDE is one such task.

WhatsThis help is essentially an on-demand, extended tooltip associated with a specific widget. It tends to be more verbose than a tooltip, but more succinct and specific than a full-blown help manual. To learn how to help improve KDE by adding WhatsThis entries where they are missing, check out the tutorial!

Dot Categories: 

Comments

by Thorsten (not verified)

Congratulations for a great tutorial Aaron!

Cheers,
Thorsten

Useful!

Why doesn't KDE provide a Wiki structure for documentation and a distributed framework for documentation translation ("grid translation").

non-programmer contributors don't know CVS and don't want to learn how to handle it. they will probably be even unable to use ftp and understand the docbook-format

And programmers are ungifted in documentation issues.

Si! A framwork for easy contributions is needed. However Aaron's article again teaches how to use CVS ecc. in the programmers way ("To get started, visit the KDE anonymous CVS documentation"). Cough! Programmers will never learn it.

Contributors don't want to learn how a programmer likes to work. This documentation is only usable for those who like to become a programmer.

Consider the ability to follow directions to use CVS as a test of your ability to contribute to the project.

It isn't really that hard, but it requires a little thought and understanding of how the project works.

If a person is willing to make the effort, invest a little time and energy into learning the process, then they may be trusted with some responsability.

Derek

Not ALL programmers do bad documenting, most. I do think however you are right about Aeron's article. As far as I know, via KDE one can easely start using CVS with a GUI.

Be proud of this CVS GUI and promote that instead of command line instructions (in this case).

by Aaron J. Seigo (not verified)

i did mention cervisia in the article. the command line stuff is very simple, however, and i didn't want to go into a huge tangent on how to set up cervisia and use it properly. if you want to provide such a patch to the article complete with screenshots, please do so and i'll add it and give you credit.

p.s. while i like the 1950's-era aerodynamic vehicle of the future ring that "Aeron" has to it, my name is actually Aaron ;-)

Sorry about that name.. I actually think Aeron is from a Final Fantasy game? Anyway, ironicly, I also use the command prompt myself and wouldnt even know how to use the GUI at this moment, so I wouldnt be much help Aaron!

No, Aeron is the famous Hermann-Miller chair, the symbol for DotComs that spent too much of their VC's money and thus were doomed from the beginning.

by Aaron J. Seigo (not verified)

yeah, but DAMN those chairs are awesome to sit in! especially when all you do most of the day is sit. =)

by Andras Mantia (not verified)

What is so hard to set up in Cervisia? I think a quick guide to set it up and use would be appreciate by non programmers. I'm a programmer, but I also appreciate a graphical CVS client. We should promote Cervisia. KDE is a desktop environment after all, not (only) a place from where you start an xterm and do the rest of things. ;-) Translators also tend to use KBabel, web page writers Quanta (hopefully) and so on. Of course, there are old habbits and favourite apps, many KDE core developers may use non-KDE apps for everyday work, but in any case we should promote KDE software whenever it is available, and especially if it's good enough.

Andras

by Aaron J. Seigo (not verified)

> ("To get started, visit the KDE anonymous CVS documentation")

yes, and then i go through it step-by-step so you can cut'n'paste your way through it. you don't really need to visit the KDE anoncvs docu, because it's all there in the article! but if you are curious, you *can* visit the documentation for more information.

see, this article isn't meant to be a "Slobbering Idiot's Guide To Placing Random Text Into KDE" it's meant to be something more on par with a high school level tutorial. if it was possible to do these things with no effort and no thought whatsoever, i wouldn't've had to write a tutorial in the first place, now would I? think about it.

to be honest, any half-motivated, computer literate 12 year old could follow that article and produce results.

now here's the part where i rant maniacally (as opposed to the above;):

it's the "suport" of people like you that makes venturing out into the public eye so very difficult for me to handle. btw, where's your amazingly useful and artfully written article for me to read and learn the Tao of writing from? and no, half-baked criticisms on web boards most definitely do not count.

by Kurt Pfeifle (not verified)

Thanks for that! I was looking into means to contribute "What's this?" bits and pieces anyway. So this is definitely s.th. I will look into. To have a *complete*, and I *mean* complete, 100%, working "What's this?" for *all* apps will bring KDE much closer to a viable corporate-used desktop system than anything else...

Cheer,
Kurt

by Robert Guthrie (not verified)

It is an impressive tutorial, and it makes sence to me as a programmer.. but i dont see anyone putting in that much effort each.. there is alot of stuff there that a small webscript can smplify (the 80 char's a line stuff for instance)

i agree with the other posters, and think that putting this effort into a web script to collect these strings, and a system to float the good ones to the top so programmers can enter them into CVS would be a better use of time..

Actually.. i take back some of what i said.. Parts of this tutorial are not misguided at all.., and incombination with a webscript idea could provide a really good soution i think...

sorry if some of this dosnt make sence, ive just felt the flu coming on, and im about to go lie down.

by konqi (not verified)

Good stuff, altough perhaps still a bit too much from a programmers perspective, like said above.
Still a good try though.

>> It tends to be more verbose than a tooltip, but more succinct and specific than a full-blown help manual.

I actually never ever use that silly help button that unnecessarily adds bloat to every dialog.

If I want to know what a specific UI part does, it makes no sense to browse through a complete manual (I already forgot what I was looking for when I finally found the text that explains what the UI does).

If only that button could be removed from the dialogs.. /me would be a happy KDE user.

by Aaron J. Seigo (not verified)

> If only that button could be removed from the dialogs

look in the window decorations control panel. you can customize which buttons are shown for many (most?) kde window decorations. just remove the WhatsThis help button and voila, you're a happy KDE user. =)

by konqi (not verified)

Actually, I rather meant those 'Help' buttons in the dialogs, not window decorations, like in the following screenshot: http://urbanlizard.com/~aseigo/whatsthis_tutorial/whatsthis_example_larg...

But thanks, didn't realize it was possible to remove them from the win decs, so I'm already a tiny bit more happy KDE user now :)

by Mario (not verified)

Please no!! The Help is only in the UI when there is no menu to put it in, I agree it could be put in the context menu instead, but most KDE applications already do this and changing would be too much work, besides I don't need the help every time in my context menu.

by Aaron J. Seigo (not verified)

so, several people have noted that they think it's still all too programmer oriented. well, it's not going to get much clearer than what's there. WhatsThis help is embedded RIGHT IN the application. it isn't some external file. so you need to enter it RIGHT IN the application's source code. fortunately we have UI files to blunt that pain. =)

as for using CVS, it's not very hard. all the commands are right there to copy 'n paste, and there's even a GUI for it, as noted in one of the Tips. CVS is simply the only practical way to make patches and have the latest code. the effort required to get CVS going to do WhatsThis is minimal compared to the effort of actually writing the WhatsThis help.

as for watching how you format your lines when editting source code files, well, that's just an unfortunate detail. if wrapping at 80 characters is beyond you, or you can't be bothered to try even a little bit, stick to the UI files where it's all handled for you.

as for using a webscript, i'll just repeat this: it's embedded in the applications!

there is a UI-files-from-CVS web-based browser in the works, but it isn't ready for prime time yet. once that is done, the you can grab UI files using your web browsing and edit them from there. but this still doesn't help with making the patches or ensuring they are up-to-date when you finish.

honestly, if it's all too much effort for you, that's cool. don't do anything. just continue to be a user that takes what is made for you. i'm not trying to convert the entire world into being KDE contributors. but there ARE people out there who want to get involved, and these sorts of things are exactly what they have been asking for.

of course, i'd be happy to see a tutorial showing how to do WhatsThis that meets the "doesn't suck because it wasn't written by a programmer" standards. ;-)

also note that some of the future tutorials in this series will not have anything to do with the source code... future topics may include bug triage, icons and other art, documentation writing, translating, user support, advocacy... bug triage is likely the next one, actually...

by anon (not verified)

> as for using a webscript, i'll just repeat this: it's embedded in the applications!

How about a webscript that automatically emails a mailing list.. that way non-programmers won't have to mess with the hard to use software that is CVS

by Eric Laffoon (not verified)

> How about a webscript that automatically emails a mailing list.. that way non-programmers won't have to mess with the hard to use software that is CVS

How exactly is CVS hard? Remembering commands, options and switches? Okay, but conceptually it's easy. Check out a repository (or if you're starting one check it in) then to get the latest update and to send your changes commit. To add files you add.

KDE has Cervisia in the kdesdk module and it makes CVS so easy it's not even funny. Before anyone tells me "but you're a developer" you should know I was not doing application development when I discovered CVS and using it to submit artwork or tag files to Quanta scared me. Then I discovered Cervisia and my world changed...

It takes about two commands to set up a local repository. Suddenly I began putting web development projects, notes, spreadsheets and everything in a CVS repository. Why? Because it's incredibly easy with Cervisia. I showed my wife and she started putting journal notes in CVS. CVS is not only dead easy with Cervisia, but there isn't any silly web interface that has the functionality, unless it hooks up to a CVS server. the odds are excellent that something you are doing now would benefit from your own CVS. It's not just developers that need to manage files with versioning.

Log in once, open Cervisia and point and click, review changed files, diff changes so you can understand what was done... Cervisia and KCompare are great tools that are easy to use... much easier than complaining CVS is hard. ;-)

by Otter (not verified)

********

so, several people have noted that they think it's still all too programmer oriented. well, it's not going to get much clearer than what's there. WhatsThis help is embedded RIGHT IN the application. it isn't some external file. so you need to enter it RIGHT IN the application's source code. fortunately we have UI files to blunt that pain. =)

********

Yup, that's pretty much the bottom line. Editing Designer files is relatively easy -- deciding which hand-created object needs to have the What's This? tag added to it is going to require the novice to follow the C++ code at least superficially. God help them when they run into objects created as a QWidget instead of a QWidget *. ;-)

Still, there's a large contingent that spends a ton of time messing with source even if they don't code. This will be a good learning experience for them and the Qt class hierarchy is so elegant, it's a great way to start.

by German (not verified)

Is it planned to translate this tutorial ?
It would very nice !
Or is there a way that people don`t speak english to help the kde projekt?

by Waldo Bastian (not verified)

KDE's source code is written in "US English". From there it gets translated to numerous languages, including German. So to add tooltips you will need to
be able to write English reasonably well. If you don't, you will still be able to help by translating the english tooltips to e.g. German if you are at least able to read English reasonably well.

If you can't read English you can still help KDE by promoting KDE in your own language, e.g. by presenting it at expositions or trade shows or by answering KDE questions on language specific mailinglists.

If you want to help with translations you can contact the team coordinator for the language you are interested in. See
http://i18n.kde.org/teams for a list of all translation teams and
http://i18n.kde.org/teams/index.php?action=info&team=de for information about the German translation team.

Cheers,
Waldo

by Wurzelgeist (not verified)

KDE's source code is written in "US English"

Typisch deutsch. Sobald ein einziger Spanier, der deutsch kann, im Raum ist, sprechen alle Englisch. Ich schätze, wenn jeder seinen Kram in seiner Sprache gepflegt hätte und dann übersetzt wird, wären wir schon weiter. Ich kann in deutsch in der Zeit wo ich auf Englisch was formuliere fünf Texte schreiben. Wenn man dann einen ins Englische übersetzt, sind es immer noch 4 mehr...

aber so wie es jetzt ist, hinkt wohl eher die deutsche KDE-Seite hinterher.

Naja. Sicherlich hat der zum Teil traurige Zustand der Doku auch damit zu tun, dass für viele Entwickler US-Englisch nicht die Muttersprache ist. Da fasst man sich dann halt lieber kurz.

by Das Koole Desktop? (not verified)

Bitte? *

* I don't speak Bratwurst-language

by CE (not verified)

Most Germans would write "der koole Desktop". ;-)
I don't know why it is used as male in German, perhaps because of "der Schreibtisch".

by schnitzelkopf@d... (not verified)

Like I said, I really don't speak German :)

by L.Lunak (not verified)

No jo, souhlasim. Od zitrka zacinam psat vsechno v cestine. Vsak vy si s tim nejak poradite.

by SadEagle (not verified)

Я думаю что всё-таки есть смысл перейти на Русский -- ведь нельзя же ожидать что люди будут пользоваться иностранным алфавитом.

by SadEagle (not verified)

The above is utf8, BTW

by AC (not verified)

001001001001101001001001001011001001111011001010010011010010
011101101001000010011110100100100111010100100100111011001001
001110100100100100100110100100100100101101100100111101100101
001001101001001110110100100001001111010010010011101010010010
011101100100100111010010010010010011010010010010010110110010
001010010011010010011101101001000010011110100100100111010010
010010011010010010010001001001001110110010010011101001001001
0010011010010010010010110110010011110110010100100110100

by AC (not verified)

You are a shame for all anonymous users (and also for Alan Cox).

by CE (not verified)

When I see that I think it's good that Russian uses cyrillic letters.

by ac (not verified)

that's not russian

by CE (not verified)

Did I state that?
But it's a slawonian language.
And I think these are more readable with cyrillic letters.

by Will Stephenson (not verified)

ärgere dich bloß nicht allzusehr drüber. Ich bin damals teils zu KDE gekommen, weil ich meine Deutschkenntnisse nicht verlieren wollte, und dachte ich konnte den tapferen KDE-leuten helfen, ihr Projekt ins Englische zu ubersetzen. Ich kam mir ziemlich dumm vor, als ich mich bei der i18n Mailinglist meldete und fand, daß beinah alles schon auf US-English lief.

Kurz zusammengefasst: Du darfst dich in deine Strings beliebig schlecht ausdrucken, es gibt immer welche, die beim Korrigieren froh werden.

Will
(IRC: Bille)

by Tim Jansen (not verified)

The problem is that many people around the world are working on the same applications. It is not realistic to use more than one language.
English is the language that every serious programmer can speak - and has to speak, because most documentation, API references, specifications etc are not available in any other language.
Even if the programmer feels more comfortable writing in his native language (and I do), it would exclude so many people from contributing that this would easily outweight any disadvantage in the documentation.

And, BTW, I don't think that there are many people capable to translate from German or any other non-English language to their native language. So it would not even work for the documentation.

by Strider (not verified)

This is a ridiculously useful article that has already had some broad appeal to non-programmers. Many non-programmers I know want to _do_ development but don't feel like they are actually part of the development process by writing howto's and making websites. This gives users a way to actually submit patches, make diffs, and get credit for code changes..

This little tutorial may do more to help out KDE than the last day or two of bug fixes. Thanks for adding hundreds to the pool of possible KDE developers.

Strid...

by annma (not verified)

yes, great article. I often meet in IRC users that are willing to learn to compile from source for whatever reason. It's not much more difficult to buid KDE from cvs and with this neat tutorial, non-developers will be able to give something to KDE. The What'sThis help is very important and as developers, we tend to forget that. I encourage people to follow the instructions in the tutorial and to be part of KDE. On IRC (#kde, #kde-devel) you will always find some help if you are stuck.

At your keyboard, 3, 2, 1...ready... go!

by KDE User (not verified)

wouldn't people like it to be as slick as gnome.org
or at least as es.kde.org

by anon (not verified)

The GNOME frontpage is cool, but the inner pages are a bit lackluster. The KDE frontpage is lackluster, but it's inner content pages are cool. I think the KDE front page should probably put less content in the front page and try to get it to fit into one page length (like the yahoo of olden times).. it seems a bit confusing.

by ac (not verified)

The kde frontpage just need a little more graphics, less blockness, maybe more colour.

But the content is good and fresh!

by dude (not verified)

yeah, they are just starting the site redesign as we speak, they started with the front page but havnt gotten to most of the rest of the site.

by Aaron J. Seigo (not verified)

how is this related to the WhatsThis article?

by Eric Laffoon (not verified)

> how is this related to the WhatsThis article?

You don't know? ;-) It's how they got here... and their own little forum that will subsume all discussions here to be the most popular talkback on your excellent story, hereafter referred to as "the KDE Front Page story".

Okay... scratch one user concentrating long enough to finish the tutorial. Next up, first person shooters... ;-)

BTW I skimmed it real quick. Excellent stuff, which I'd expect. I'll read it again later when I can savor it.

Cheers

by anon (not verified)

Obviously you haven't visited the dot recently! :)

by kde user (not verified)

well, there's so much stuff on the webpage so it's hard to know
"what things are". but maybe "what's this" popups on the webpage
would be too much.

by John Herdy (not verified)

See title, just want to show my appreciation.

by John Herdy (not verified)

See title, just want to show my appreciation.

by Mario (not verified)

This is one area where KD Eis clearly lacking and now anybody can add more helpful What'sThisHelp to KDE with a bit of work.

Thank you!

BTW: While this wish http://bugs.kde.org/show_bug.cgi?id=59859 would not be encessary if every part of KDE's inteface had a What'sThis tooltip, that probably won't happen so we still need a way to make the user know wher ethe tooltips are. For example when he clicks the tooltip icon and he hovers over widgets with tooltips, his mouse cursor should change so he would know that there is a tooltip there.

Vote for this bug: http://bugs.kde.org/show_bug.cgi?id=59859 and maybe Trolltech will fix it.