Introduction

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.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license can be found at http://docs.kde.org/HEAD/common/fdl-license.html.

PLEASE NOTE: This is a draft so don't jump in your chair if something is unreasonable. But please tell the authors(kde-usability) if they are unreasonable. Otherwise you will really have to jump in your chair.

These guidelines defines a set of policies, recommendations and conventions touching directory layout, usability issues and general design agreements relevant for KControl Modules(KCMs from now on) to be used with KControl. The KCM technology was originally designed for KControl but has since then been adopted in many other situations. KInfoCenter, Kopete, Kontakt and Konqueror is some applications who also uses it. Please note, these policies only applies for KCM's which will be used in KControl, although a lot of the recommendations is healthy for other KCMs as well.

These guidelines assumes a basic understanding of the technical side of KControl and KCMs which are covered in the KControl Module HOWTO. In case it does not cover your wondering, don't hesitate to drop a line on kde-devel.

These guidelines establishes a set of recommendations and policies ranging from usability, such as naming and layout, to how to arrange code and name files, in order to make life easier for us developers as well as to promote usability and code quality. In order for this to succeed, these guidelines must be followed. But, it should not be followed in a foolish way, corner cases always exists and these guidelines can not cover them all.

If there is an interest to not adhere to these guidelines the right way is not to just ignore the guidelines and go hacking away in an own style - KDE is a community project and the technological nature of KControl can not handle it - each KCM are not independent but part of a whole. As soon there is a case not covered in this guide, or the guidelines seems to simply be wrong the issue should be raised on the mailinglist kde-usability so your idea can be peer reviewed and discussed, and these guidelines changed accordingly.
As soon as you look at other KCMs in order to see how they behave or have solved a problem it probably mean these guidelines have not covered that area and must be completed - raise the issue on kde-usability.

Suggestion, questions and general discussion regarding this document can be directed to the kde-usability@kde.org mailing list.

If you need to get in contact with the maintainer for a particular KCM, that information can be obtained from PACKAGE/kcms/README, where PACKAGE is the relevant KDE module, for example kdemultimedia. There you will also find information specific for that module's KCMs, such as design guidelines specific for that module. Usually, PACKAGE/kcms/KCM/README can also be useful, where KCM is for example the "keyboard" KCM.

A good KCM to study which follows these guidelines correctly can be found in kdebase/kcms/useraccount/