[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-usability
Subject:    Summoning KControl development - Will it work? Mesa wonders
From:       Frans Englich <frans.englich () telia ! com>
Date:       2004-01-08 0:23:03
Message-ID: 200401080123.03211.frans.englich () telia ! com
[Download RAW message or body]

I responded to William's "KControl brainstorming" with a proposal to 
KControl's problems and the content below as well as the attached files is a 
refined and extended description of it.

We all know KControl has severe usability issues. This proposal does not focus 
on the actual usability problems but tries to tackle the problem from another 
side by explaining the cause to the usability problems being a lack of 
organization.
KControl and all its modules needs coherency and consistency which is provided 
by a continuous and centralized development. Currently, that is not the case. 
Every KCM(which usually is a very small piece of code) is basically 
maintained by its own maintainer. In other words, there is almost as many 
people as there is KCM's maintaining and applying their own views on such a 
critical part as KDE's KControl. Furthermore, it is very difficult to 
maintain KControl and all its children because the KCM's is spread out all 
over repository - and when you try to pull a change you will each time have 
to face a discussion with the maintainer of that KCM.
So, in order to build a ground which usability /then/ can be built is the 
following:

To a beginning all KCMs of respective package is placed in the subdir "KCMs" 
of each package. Each package(eg. kdemultimedia) has it's own KCMs 
maintainer.
In kdebase/KCMs, resides a KCM_CONVENTIONS(except its own modules) which 
documents conventions and design guidelines for KCMs which must be followed.

This structuring have some clear advantages:
1) Makes it more failsafe to maintainer dropouts since others are familiar 
with the job.
2) Lowers the entry bar by making it easier to navigate the source(by 
documentation and file reorganization).
3) Makes it easier to reach decisions in usability and provide consistency 
because of documentation.
4) Centralizes development since a small group(with good communication skills) 
are in charge. For example, it won't be possible to sneak in a KCM(!) without 
it being agreed and made sure it fits in as a whole.
5) Better maintenance, by the maintainer can focus and concentrate on a 
special part of code. You don't have to fly all over the kde source - you can 
specialize and get familiar with kdenetwork ie.
6) Maintaining /one/ kcm is boring for several reasons. But when you're 
responsible for all KCM's in kdegraphics for example, it has become a 
challenge as well as it is rewarding - improving modules and incorporating 
consistency is done on something you /own/, instead of each time patching 
around on different people's work. Being a "kdemultimedia KCM maintainer"(for 
example") is an identity representing work which is appreciated.


The lowered entry bar and the increased appreciation of those who hack on 
KCMs, blows new life into KCM/KControl development/maintenance and lays a 
ground for solving the usability issues. It also goes well in hand with the 
Quality Team proposal.
Wild suggestion: This group of maintainers should perhaps have their own 
mailinglist, kde-kcm-devel with focus on usability issues concerning KControl 
and KCMs. Reducing noise on the main mailinglists as well as letting the 
group work uninterrupted..

Attached is two files which after my idea should be placed in 
kdebase/KCMs/(this is all post 3.2 ofcourse). KCM_CONVENTIONS mentions a lot 
of practical issues and hopefully clears any question marks regarding this 
proposal. It is of course a Draft and can use as much input as possible and 
will evolve with usability development as well as the refinement of this 
idea. Again, it is a draft and is ment to be corrected - some of the 
statements is from my gut feelings.

Quoting Aaron:
"I haven't taken part in that conversation because they are going over the 
same ground that has been well travelled in the past. it's really frustrating 
to engage the same discussion with the same dead ends repeatedly."

No doubt and fully reasonable. But now is the time to shoot down this idea if 
this is yet another dead end. Someone will have to explain why this idea is 
not worth backing up, or otherwise I will continue bashing forward..
We need to know if this proposal is somewhere near to be in the right 
direction and what corrections needs to be done. Also what is missing and 
could be complemented. A technical issue springs to my mind: Is there any 
trouble in moving the KCM's to one place(as the file describes)? 

Thank you for your time!


			Frans





["KCM_CONVENTIONS" (text/plain)]

Copyright (c)  2004  Frans Englich <frans.englich@telia.com>.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".


This file describes the organisational layout and file structure for KDE's 
KCMs(KControl Modules) as well as design recommendations and conventions 
used.
Writing KCMs is covered in KCM_HOWTO.
Issues specific to kdebase's KCMs as well as the current maintainer
information can be obtained from README.


This file exists in order to make decision regarding KControl and its
KCMs centralised as well as bringing some coherency to development.
If you have valid reason for not following these guidelines please 
speak up on the mailinglist kde-usability so your suggestion can be 
peer reviewed and this file eventually changed to reflect the new 
conventions. Naturally, do not change the content of this file(except 
obvious typos) without having reached consensus with other developers. 
Furthermore, any agreement regarding KControl's design and conventions 
must be documented in this file. It is essential this file reflects the 
practices in use, otherwise it will loose it influence.

General discussion about usability issues should be done on the 
mailinglist kde-usability. In order to get in contact with the maintainer
of the various modules please consult PACKAGE/KCMs/README where PACKAGE is 
the relevant kde package, such as kdegraphics.

--- Directory Layout and Filename Conventions ---
In each KDE package which contains KCMs(for example kdenetwork) 
a top directory named "KCMs" exists which contains everything related to 
the KCM's for that package, regardless of what application or 
functionality the KCM represents.
Each "KCMs" contains a README file where the maintainer is listed 
as well as other information specific information for that package's 
KCMs(kdebase is one exception which also contains this file).
For KCM's and their associated files a set of filename conventions 
exists with must be followed:

* All the KCM's files resides in a sub directory of "KCMs". The 
name of that directory is the same X-KDE-Library for that module.
Ie, if a KCM's desktop file contains "X-KDE-Library=kmix" all its 
files resides in "KCMs/kmix/".

* The name of the desktop file is the KCM's library name prefixed 
with "kcm_". For example "kcm_kmix.desktop".

* If the KCM has an icon specific for the KCM its basename should be 
the same as the library name.

* The main source file and its header should be named main.cpp and 
main.h, respectively.



--- A Valid KCM ---
In order for an KCM to be good and valid it must conform to:

1) KDE Licensing Policy. Basically, a OSI approved license 
as well as correct license and copyright headers. For details see:
http://developer.kde.org/policies/licensepolicy.html

2) KDE User Interface Guidelines. Please see:
http://developer.kde.org/documentation/standards/kde/style/basics/index.html

3) the conventions and recommendations in this file.

If the KCM does not conform, it is considered a broken KCM.

These guidelines exist in order to make the KCMs look consistent, 
be pleasent for the user and blend with the rest of KDE as well as 
ensuring KDE stay out of legal trouble. It also makes life easier 
for use developers.



--- Name Recommendations ---
When picking or changing a name(that is the Name directive in
the .desktop file) for a KCM it is good idea keeping the 
following issues in mind in order to promote usability and 
consistency between the modules:

* Try to keep the phrase short. Shorter phrases is easier and
fast to interpret and give better options for designing the layout. 
From a esthetically perspective it also looks cleaner and simpler.

* Avoid complex phrases involving backslashes("/)" and paranteses
for the same reasons as above. 

* Avoid including words like "Management" and "Configuration" etc. 
since it is abundant - KControl is all about that which the user 
already is aware of. Furthermore, such terms does not inform the 
user about what Your module contains, except that it is for 
configuration or management(and that is already clear since it is 
in KControl).

* KControl as the rest of KDE targets a wide audience where a 
significant part of the users does not have technical expertise. 
In order to have a compelling interface it is important to avoid 
technical and "scary" terms. Words used should an average user be 
able to understand.

The above name recommendations is guidelines and must not be 
strictly followed. If the name demands to be longer than average
in order to be informative that is of course ok. Similarly, don't
simplify words in case it then does not reflect the content. The 
recommendations exist to make the names informative, representative
for the content and easy to read - not the opposite.
The recommendations can also be applied on phrases used elsewhere in 
the KCM.



--- Technical Recommendations ---
When building a new KCM or improving an old a set of
KDE technologies is preferred in front of others:

* Use .ui files instead of handcrafted
Graphical user interfaces designed with QT Designer is preferred
instead of handwritten ones because 1) It allows people without 
C++ experience to modify GUIs; 2) It is safer since it is not 
manually written code; 3) It allows more obtrusive changes to be 
done in code freezes; and 4) Usually more efficient and faster 
code.

* KConfigXT framework instead of handcrafted configuration code
The rationalis is similar to the above with notable addition: 
it saves disc space on installed clients.

These recommendations exists in order to make development faster 
and easier resulting in better and bugfree code but neither these 
recommendations should be followed blindly. For example, if a 
handcrafted GUI for some rational reason(which is different from 
"preferred by developer") that should be chosen. 


["README" (text/plain)]

The current maintainer of kdebase's KCMs is:
NAME <EMAIL>


Please see kdebase/kcontrol/KCM_CONVENTIONS before 
modifying any KCMs. Thank you.


The Content of this Directory:
README		- This file
crypto		- SSL stuff
[etc]

Contributors:
...



_______________________________________________
kde-usability mailing list
kde-usability@mail.kde.org
https://mail.kde.org/mailman/listinfo/kde-usability


[prev in list] [next in list] [prev in thread] [next in thread]