KDE Doc: Content of the HIG
frans.englich at telia.com
Thu Aug 26 04:59:30 BST 2004
On Wednesday 25 August 2004 13:20, Aaron Seigo wrote:
First of all, I assume all references to the "current HIG" is to the recently
announced docbook replacement on usability.kde.org:
> the HIG needs to be written from scratch, as
> the current set of guidelines is too limited even as a starting point.
I assume we're talking about content here; My view is it would be better to
start from the current guidelines(yes, actually!) even if it would mean the
new version is developed in parallel with the current, and even if we in the
long run will replace it all anyway. I think we should avoid a large initial
threshold, and go inclemently with small, stable improvements. Of course, if
several sections needs to be replaced at once, we shouldn't hold it back, but
I think it can be written in small steps(chapter by chapter, or even sect1 by
sect1). Feel free to explain why, the rationalis to why you think it is too
limited even as a starting point.
> is proposed that this new HIG will be made up of several parallel
I assume you mean "in line" comments, like how Implementation Notes in the
current HIG looks like. I think it's a good idea; it communicates highly
relevant(mandatory) content in a separated way.
> Developer Guidelines
> this part will appear much like our current guidelines: straight to the
> point without much sidetracking into usability theory
> this part will provide the usability reasoning and theory behind the
Putting the "why" in the guidelines is similar to adding a programming book to
an API reference. Here's why I think it's not a good idea:
* If we (try to) explain why the guidelines are as they are, we will end up
with a incredible fat book where the strict rules are vaguely communicated.
* Explaining the why is an incredible large and difficult task. If that fails
or is not complete it undermines the HIG, it also means less work on the
* The rationalis is irrelevant to the content which should dictate how
interfaces shall look -- people don't need to know why, but we need a
mentality where the HIG is The Bible, and do the usual kde-cvs monitoring.
* Rationalis assumes a certain reader level.
* It undermines the authority of the guidelines -- discussing why, means
questioning, and hence it's validness is partly dependent on the reader's
knowledge. We will perhaps hear things as, "But I didn't agree with why
it should be done like that", "It didn't cover argument X", or individual
ideas emerging form the rationalis.
We definitely need "usability knowledge" docs, but not in the HIG, I think.
> code snippets, screenshots, etc demonstrating the guidelines in action
> Usability Checklists
> a series of quick checklists that can be used while developing UIs or
> when auditing them to ensure compliance with the guidelines
Yes, that would be useful. I see the GNOME have it in their HIG. I'm
wondering; if we have a document which have usability HOWTOs, rationalis
etc., perhaps that would be better suited there? For example, imagine we
write a "How to write usability reports" howto -- it's of the same type as
"usability checklist" but not suitable for the HIG. I think we must draw the
line somewhere between Guidelines and "Knowledge", otherwise it'll go crazy.
Separating guidelindes from "knowledge stuff" also allows to go full
speed on both.
> Usability Principles
> general usability principles towards creating highly usable interfaces.
Yes, we currently have a page long chapter, rambling on that. That chapter
would be rather generic(obviously rewritten) -- I volunteer for writing a
"Chapter Usability Principles" draft.
> this will likely consist of several articles that may be of interest to
> developers and others interested in general usability.
From an organizational perspective, I see two reasons related to this, to why
usability can be better in KDE: 1) A lack of good HIG; 2) A lack of
educational/knowledge-orientated documentation about usability.
For the second problem I started the KDE Usability Articles project, which
exactly aims for taking care of the why/rationalis-side of usability -- a
documentation platform which people can "learn" usability, find inspiration
and on the shoulders of giants invent new things. (I think much of the
endless threads which were common kde-usability is caused by people have no
idea what they're talking about..)
(the grayed out articles are written, I've just not found the time for feeding
them for review, due to finishing the HIG in time for aKademy)
It was announced on kde-core-devel/kde-usability 2(?) months ago, and there
have been about 3 threads about it on kde-usability. What are your plans with
the KUA, considering the other documentation efforts?
I think the KUA combined with the HIG is a complete combination.
> each of these components will be viewable in part or as a whole, allowing
> developers to see just the guidelines themselves and the examples, for
> instance, while those more interested in usability as a topic may choose to
> display the rationals as well.
Having it separately, like the KUA, would mean we only need one export of the
HIG(I assume a customization layer would swallow/allow the various elements).
Announcement of Docbook'ed & moved HIG:
Example of Implementation Note in HIG(scroll down a big)
More information about the kde-core-devel