<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
 <TITLE>Gideon Documentation Review</TITLE>
 <LINK HREF="index-1.html" REL=next>


</HEAD>
<BODY>
<HR>
<H1>Review of Gideon User Interface and Documentation</H1>

<H2>Ian Wadham, ianw@netspace.net.au</H2>
25 September 2003
<P><HR>


<H2>Introduction</H2>

Amilcar do Carmo Lucas of the Gideon project (KDevelop 3) has invited
me to write this review, but before I begin, perhaps I should introduce
myself.  My home is in Melbourne, Australia, a long way from the KDE action.
I meet very few people here who know anything about Linux or KDE, so I
am totally dependent on documentation and KDE newsgroups.  My Internet
connection is dialup and 28.8K bits/sec.  Furthermore, my family and
friends use the same line for phone calls.  So it is impractical
for me to download megabytes of files or spend hours reading
documentation on-line (even if I could absorb it in that form).
<P>
My recent professional background has been in UNIX, relational
database applications, 4GL (fourth generation languages), C, X Windows
(on Sun and H-P) and the K Shell (similar to "bash"), but I started
in computers in
1964 and retired about five years ago.  One of my goals had been to find
out more about Linux, but I never had the time while I was working,
what with preparing for the Millennium Bug and all that.  Then my
son bought me a copy of SuSE Linux 6.3 (with KDE 1).
<P>
After teaching myself something about C++, I had been looking for a
non-trivial project on which to try it.  Then I found KGoldrunner, a
re-creation of my favourite Apple II game (Lode Runner), tucked away among the
KDE 1 "alpha" packages ...  Some years and two versions of KDE later,
I have been using Gideon while converting KGoldrunner into a KDE 3
application, for release with KDE Games in KDE 3.2.
<P>
My experiences with Qt, KDE and Gideon have not been good: in fact
I have rarely encountered such a difficult development environment
(maybe the RSX operating systems on Digital's PDP-11 series).  When
I changed to KDE 2, nothing in my application would work, not even
the Makefile's and, at the time, I could find no useful documentation on
KDE 2 development.  There was plenty on Qt 2, though it was not always easy
to understand.  To be able to keep developing, I deleted all references to
KDE libraries from the KGoldrunner source code.  Drastic, yes, but
if software does not have good documentation that is also easy to
find, it is almost impossible to use.  It is as if the software
did not exist.
<P>
So that is where I stand on the subject of documentation.  I am
particularly keen to see Gideon well documented.  It could become
a gateway into KDE and Linux for a whole new generation of developers
with other backgrounds and they in turn could help establish KDE
and Linux as a leading personal computing environment.


<H2>The Subject of this Review</H2>

This review is of the "KDevelop 3 User Manual", but it also touches
on aspects of the KDevelop 3 user interface and KDE 3 documentation
in general.  KDevelop 3 is an integrated program development environment
which is frequently referred to by its project code-name, "Gideon".  It
runs within the KDE 3 desktop.
<P>
The version of the documentation being reviewed is as distributed with
the Alpha 6 version of Gideon on or about 9 September 2003.  This review
has been updated slightly to cover changes I have noticed as at 25 September,
but not necessarily <u>all</u> changes between those dates.  I'm shooting
at a moving target here.
<P>
Before beginning a point-by-point review, I would like to discuss some
general principles of documentation which may seem obvious, but are
often breached in the Gideon documentation and in KDE 3 documentation
generally.  Those breaches make KDE 3 and Gideon hard for a newcomer
to use and may turn them away or make them miss many of the benefits
of KDE 3 and Gideon.  I must add, however, that Bernd Pol has
started doing a splendid job of remedying some of the problems in the
Gideon documentation.


<H2>Considering the Audience and Objectives</H2>

Before writing a document or designing a piece of software, it is
important to consider who will be reading or using it, what their
objectives are and what objectives you hope to achieve with those
people.  You should write and design differently for children and
adults, for example.  Their objective might be to have fun with
your software and yours might be to entertain them and perhaps
teach them something.
<P>
So who are the intended users of Gideon?  Obviously "developers":
but what sorts of developers?  What do you expect them to know
already?  How much do you expect them to learn or already know about
the finer points of development in the KDE environment?  Is Gideon
just a GUI substitute for command-line working with various programming
tools or are you attempting
to hide the technicalities and automate development work, leaving
the developer free to concentrate on his or her code and testing?
<P>
Is Gideon only aiming at KDE project team members who already know
all that stuff about KApplication, KMainWindow, kpartgui, *ui.rc,
KDialogBase, CVS, KDE CVS, automake, autoconf, M4 macros, *.desktop
files, KDE icon naming, KParts, DCOP, XML, docbook, KDE directory structure,
KDE CVS directory structure and KDevelop project directory
structure?  Or is Gideon aiming at developers who come from other
cultures and just want to concentrate on developing their
applications and adapting them to KDE, without having to learn too
much about the technical details and without having to
learn several new languages (Automake, CVS, XML, etc)?
<P>
How would an experienced Windows, C++ and Borland developer get on
if he or she decided to try out development with Linux, KDE and
Gideon?  Such a person would probably be a great asset to the KDE
project, but I believe they would be scared off fairly quickly,
especially if they are not as idealistic as I am about free software.


<H2>Introducing Terminology Properly</H2>

There is a major problem involved in writing any document.  That
is to understand what your readers are likely to know already,
what they may need to be reminded about and what is likely to be
completely new to them --- particularly with regard to technical
terms.  As a general rule, you should always explain a
technical term the first time you use it and you should highlight
that usage somehow, so that the reader can easily go back and re-read
the explanation if necessary.
<P>
Using technical terms without explanation makes a document largely
unintelligible to a new reader.  If
the reader does not understand your terms, he or she will not
be able to use the related software feature effectively and some
of your best ideas may go to waste.  As the English poet Thomas
Gray wrote:
<PRE>
Full many a flower is born to blush unseen
And waste its sweetness on the desert air.
</PRE>
Don't let that happen to your best ideas!
<P>
The KDE Library documentation
is particularly prone to this problem and that makes it very
difficult for a newcomer to use the library effectively.  Consider
the following extract:
<PRE>
KConfig Class Reference

Access KDE Configuration entries. KDE Configuration Management class. More... 
</PRE>
which points to ...
<PRE>
Access KDE Configuration entries. KDE Configuration Management class. 

This class implements KDE's default configuration system.
</PRE>
and if you do not know what "KDE Configuration" means, you are no
wiser.  I think KConfig does something important in KDE applications,
but what?  Maybe I can guess, but how can I be sure?  Should I risk
including it in my application when I don't really understand it?
Maybe my ignorance of it will cause some subtle bug in my application.
It might be safest not to use it ...
<P>
If you already know what KConfig does (as many readers of this review will),
try changing "configuration" to "mynydd" (a Welsh word) everywhere in the
above and you should see what I am getting at.
<P>
Even my Oxford Dictionary is no help in understanding KConfig.  It
defines "configuration" as "an arrangement of parts or
elements in a particular form or figure" and, in computing, as
"the interrelating or interconnection of a computer system or
elements of it".  That is exactly how I have understood and used
the term for nearly 40 years, but "configuration" seems to have
a quite different meaning in KDE.  What is it?


<H2>The User Interface is Half the Battle</H2>

A well-designed user-interface will remove much of the need for
documentation.  Or, taking another view, the user-interface is
actually <u>part</u> of the documentation.  What is good user-interface
design?  That is hard to define, but easy to test.  If the majority
of users can work out how to use your application, without being
told and without reading the manual, then you have a good user-interface
design.  It does not matter whether it has cool graphics, tasteful colours
and buttons with a rounded look, the ultimate test is whether it is
actually easy to use.
<P>
An interface can be hard to use even if it is beautifully drawn ...
and so it is with KDevelop 3 (Gideon).  This must change ... and soon.
<P>
What is the problem?  Mainly it is Gideon's failure to follow the principles
outlined above.  The designers and writers of Gideon do not seem to have
a clear picture of who their target users are, what their objectives are
and what objectives Gideon is trying to achieve.  Furthermore, the menus,
dialog boxes and tool tips in the user interface are peppered with technical
terms that only a KDE expert would understand.  Such an expert would
scarcely need to use Gideon.  
<P>
Of course, it is not possible to define terms in the short pieces of text
that appear in menu items and tool tips, which is why those texts should
avoid, as far as possible, all terms the user might not know.  Gideon does
bring up messages in the status bar as you move the mouse over the menu, but
those are easily missed because the user's eye is directed at the menu area
amd the mouse pointer, not down at the status bar.
<P>
In dialog boxes, tips of the day and "What's This" messages there is more
room to explain things, but even the tips are full of unexplained terms
and are therefore almost useless as tips.  They do mention how handy "What's
This?" messages can be, but Gideon has not implemented "What's This?".  <u>Late
Note:</u> Automake Manager tool buttons and some menu items have
"What's This?" as at 25 September.  Some are good, but several still
have unexplained technical terms in them.
<P>
The greatest problem is undoubtedly Gideon's addiction to toolbar buttons.
There is hardly anything Gideon does that is readily explained by a small
picture, let alone a miniscule one (4x4 mm).  Why?  Firstly, most of what
Gideon does is fairly abstract (Build Project, Run Configure, Add Existing
File) and is therefore difficult to illustrate with anything meaningful.
Secondly, most toolbar buttons relate to <u>actions</u> (verbs) not
<u>objects</u> (nouns) and it is always more difficult to illustrate
an action (think of "catching a train" as opposed to "a train").  So
most of Gideon's buttons are unintelligible, which means you have to
hover over them with the mouse and wait for the tooltip to come up,
thus it would be quicker to use menus (preferably popup) or text buttons.


<H2>Problems with the Automake and QMake Manager Interface</H2>

The Automake and QMake managers are a central part of
KDevelop and should be given <u>far greater prominence</u>, both in the
the documentation and in the user interface.  Instead, they offer some
particularly bad examples of the above user-interface faults.

<H3>What to Call Them?</H3>

The use
of the terms "Manager" and "Project Manager" is misleading, to begin
with.  Things like the KDE Features List, KDE Schedules and KDE CVS
Repository are more in the nature of Project Management tools, as
normally understood in the computer industry.  GNU documentation describes
Automake, Autoconf and Libtool as the "GNU Build System" and Qt documentation
describes QMake simply as "a tool ... to write makefiles for different
compilers and platforms".  Please can we use more accurate and meaningful
terms for Automake Manager and QMake Manager?  Newcomers to KDevelop
will then have a better chance to realise their significance and usefulness.

<H3>Visibility and Access</H3>

The next problem is that the two Managers are almost invisible in the
user interface.  The only means of
operating them is by a tab tucked away on the right of the
screen (in Ideal mode).  When you open the Automake Manager its operation
is by microscopic toolbar buttons with mostly meaningless icons (I use a
1280x1024 flat LCD screen, 33.5x27.0cm).  When
seen with a watchmaker's eyeglass, the two most recognizable pictures
are a red Flash Gordon style rocket ship (which means "Build" apparently)
and a spanner ("wrench" in American) for "Options", a vague term which
can mean many things.
<P>
Yet a single facility, Automake Manager,
encompasses the entire structure of your KDE application, including all the
mysterious components required by KDE (.desktop, ui.rc, .lsm, icons, etc.),
and it completely controls what happens at Compilation and Installation
time.  Even so, such simple widely-used "journeyman programmer" devices as
conditional compilation settings and library linkages are hard to find --- 
hidden away in dialogues under the buttons --- and they are not easy to use
when you find them.
<P>
QMake Manager is slightly better, but not much.  It lacks the clarity
and simplicity of working directly with a ".pro" file, even though
that file forces certain syntactic inelegancies upon you.

<H3>Is it Safe to Edit ".am" and ".pro" Files?</H3>

And what if you prefer to work directly with the ".am" or ".pro" file texts?
To what extent is that supported or not supported by Gideon?  The situation
was quite clear in KDevelop 2: the Makefile.am contained a comment along
the lines of "Put your own stuff after this point.  Everything above will
be over-written by KDevelop".  In Gideon, some direct edits seem to "take"
in Automake Manager and some do not.  Are there rules for this?  Does it
matter if Automake Manager gets out of synch with the actual ".am" files?
How can we Gideon users be sure?
<P>
In QMake, the ".pro" files are written in simple language that any
experienced C programmer can understand (unlike ".am" files), so the
need for a QMake Manager just about disappears (see
/usr/lib/qt3/doc/html/qmake-manual-3.html), though the situation
becomes less clear when you come to INSTALLS.

<H3>Some Needed Interface Improvements</H3>

The Automake and QMake Managers are crying out for better
interfaces.  I would suggest the project's selected Manager should have
an entire menubar item to itself, in parallel with the Project,
Build and Debug menus.
<P>
There is scope too for clarifying and standardising the terminology used,
making its usage more consistent
and making the various dialogues more intuitive.  Why "subproject"
when it is known in other applications and Gideon as "subdirectory"?
What is a "target" in Gideon?  Clearly it is not the same thing as
"all", "install" or ".o" in "make".  Why does the "Subproject
Options" have "Prefixes" on one of its tabs, when it is really
"Installation Directories" (I <u>think</u>).
It took me days to realise that this was the place to add a
target installation directory for my application's data-files, but I am still
confused by this, I find.
And whatever are "services" and "applications" in the Automake Manager context?
And what is "Flags" (a vague term) in the "Target Options" dialog.  The
box marked "Other" (even more vaguely), seems to contain nothing less than
the all-important library search path.

<H3>The Need for Input Validation and Prompts</H3>

There is also a great need for input validation in the dialogs, as
there always is in any interactive application.  It would
be helpful also to have lists
of possible entries and lists of current settings.  If you enter
something like $(LIB_TYPINGERROR), Automake Manager will not
say "don't know what that means", nor will it give you a list of the
library symbols it does
recognize, nor a summary of what is on those libraries, nor will it give you
current settings (values) of the symbols.  The same is true with other
symbols, including the all-important $(prefix).
<P>
Consequently, unless you read the fine
print in the compiler and linker output or run a "find" command after
installation or "grep" through thousands of lines of Makefile's, you
cannot be sure what is going into your build or why your application
failed to build or where your application
is actually being installed.  A sorry state of affairs.  Gideon once sprayed
my application files all over my root ("/") directory because it
had set $(prefix) to the null string - very unfriendly.

<H3>I Tried to Help, But ...</H3>

I commented on these validation issues in bug reports
<A HREF="http://bugs.kde.org/show_bug.cgi?id=62288">62288</A>,
<A HREF="http://bugs.kde.org/show_bug.cgi?id=62289">62289</A> and
<A HREF="http://bugs.kde.org/show_bug.cgi?id=62291">62291</A>.  At
first my comments were met with incomprehension, then cries of
"too hard", then Stephan Kulow (the legendary "coolo") stepped in
and gave us a 1-line hint, which I investigated and enlarged upon.
<P>
It turned out
that Gideon keeps the required information lying around in
directory "autom4te.cache", for some other reason, so why not use
it for validation?  I suggested that in an email to bug 62288, but
finally the bug was marked RESOLVED, INVALID,
without comment and apparently without identification of the
individual responsible.  I am truly disappointed.  The Gideon team gets handed
the solution on a plate, plus some ideas on how to improve Gideon dialogs,
then does nothing about it: just marks the whole thing RESOLVED, INVALID.

<H2>KDevelop 2, Where Are You Now?</H2>

By the way, KDevelop 2 had built-in manuals covering KDE symbol
names and conventions (e.g. kde_datadir).  Whatever happened to
them?  I shed a nostalgic tear.  KDevelop 2 was not as pretty to
look at as Gideon, but it was a lot easier to use it and get
results quickly and reliably - and that is what counts when you
are developing an
application.  Gideon could be even better than KDevelop 2, but it is certainly
not there yet.  Please rethink your objectives, your approach
to your users and above all your user interface.

</BODY>
</HTML>