[Kde-pim] jargon is bad! :)

Tue Mar 16 17:55:12 GMT 2010

On March 16, 2010, Thomas McGuire wrote:
> Hi,
> 
> On Tuesday 16 March 2010 02:40:03 Aaron J. Seigo wrote:
> > ok, so the point of this email is to note the obvious: displaying jargon
> > to the user is bad. the average computer user does not know what
> > "compositing", "akonadi" or "nepomuk" are. they do understand what
> > "desktop effects"[1], "personal information service"[2] or "search
> > service" is.
> > 
> > in my testing of KDE 4 here with real, actual non-technical KDE users (so
> > not people who use MS Windows or Mac usually and are randomly subjected
> > to KDE for a testing session ;), something that keeps coming up is the
> > jargon that gets "leaked" out into the UI.
> > 
> > this is not a small issue. it's the difference between "this is
> > difficult, hard and sucks" and "i like this". seriously, even in failure
> > people respond better when the messages they get are understandable and
> > human. few things freak people out more than not understanding something
> > they just read when it is something they feel they probably need to
> > (like an error message).
> > 
> > i've fixed up nepomuk once or twice (but jargon continues to leak as new
> > strings are added!), i've just looked through kwin's messages and fixed
> > them up (after testing the results on a user here) and akonadi hasn't
> > been touched yet (and is full of visible jargon).
> > 
> > please spend the few minutes necessary to improve this. it is really,
> > really important. and please help prevent new strings with jargon from
> > creeping in.
> 
> I absolutely agree. In KDEPIM, we have to be careful about this. For
> example, we should use the term "Folder" instead of "Collection" and
> "Mail", "Contact" etc instead of "Item".

definitely :) it's really hard when you are working on something so 
technically demanding and intricate as Akonadi not to have these details leak 
out into the UI, but it is possible as long as people are aware of it.

> Sometimes, using the term "Akonadi" can not entirely be avoided, and I'm
> unsure what to do about it. For example, when KMail can not work because
> Akonadi is not running, we have to tell the user in some way, like "The
> Akonadi PIM framework is not running, bla bla.".

in KWin there's a message that used to say things like "Compositing is not 
supported on your system. Xorg development headers were not installed." the 
second sentence is unavoidable jargon; there's no other way of saying it and 
it is critical information to troubleshooting the problem. so what i did was 
warn the user that technical information was coming their way and replace the 
jargon that i could. it now says things like: "Desktop effects are not 
available on this system for the following technical reasons: Xorg development 
headers were not installed."

so the user is told what is happening in as-plain-as-possible-language, warned 
that there's technical babble coming and then the technical babble happens.

in the case of KMail failing because Akonadi is not available, the questions 
i'd ask myself when writing that message are:

* what parts of the jargon are actually useful for troubleshooting and fixing 
the problem?

* can i start the message with something that has little or no jargon in it so 
that the user knows at least what is going on

* how can i let the user know that there is jargon coming and what they should 
do with it?

e.g. maybe start with: "KMail could not load your email or contacts. The 
personal information services on this machine could not be contacted." 

then if it is useful to know that Akonadi is the culprit, maybe do something 
like:

 "KMail could not load your email or contacts. The personal information 
services (Akonadi) on this machine could not be contacted." 

or

 "KMail could not load your email or contacts as the required personal 
information service is not running on this system. Please check the 
configuration for the Akonadi personal information service in the <location of 
the configuration or other useful troubleshooting information>." 

> Another example: The mail import tool (still wrongly called KMailCVT) can
> import mails into Akonadi, the mails can not just be used by KMail, but
> also by other applications. Currently the introduction page there says
> "This program will help you import your email [..] into Akonadi". Any

if it is launched from within an email program, such as KMail or Mailody, then 
simply "This program will help you import your email and contacts." is 
probably enough since the context is already obvious.

if it is meant to be launched as a stand-alone application, e.g. from an 
application launcher (and just because it -can- be launched from a konsole may 
not mean that requirement is met :), then perhaps some additional information 
needs to be offered, e.g.:

"This program will help you import your email and contacts into the personal 
information service for your login on this computer. After a successful 
import, your data will be available for use by any application which uses the 
Akonadi personal information service such as Kontact, Mailody or Lionmail."

and maybe even offer ways to launch them when it's done. in fact, the app 
could even have two modes depending on command line switches: a "launched from 
an app, so the context is obvious to the user" and a "launched stand-alone, 
user will need more hand-holding in the directions" mode.

so with a bit of creativity, i'm sure you can come up with a really good 
solution even for this trickier problem :)

-- 
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Qt Development Frameworks
_______________________________________________
KDE PIM mailing list kde-pim at kde.org
https://mail.kde.org/mailman/listinfo/kde-pim
KDE PIM home page at http://pim.kde.org/