KDE Doc: Content of the HIG

[Frans Englich]

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[1] docbook replacement on usability.kde.org:
http://usability.kde.org/hig/

<SNIP>
> 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.

> it 
> is proposed that this new HIG will be made up of several parallel
> components, 

I assume you mean "in line" comments, like how Implementation Notes in the 
current HIG looks like[2]. I think it's a good idea; it communicates highly 
relevant(mandatory) content in a separated way.

> including: 
>
>  Developer Guidelines
>   this part will appear much like our current guidelines: straight to the
>   point without much sidetracking into usability theory
>  Rational
>   this part will provide the usability reasoning and theory behind the
>   guidelines

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 
actual guidelines.

* 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.

>  Examples
>   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..)

http://usability.kde.org/kua/current/

(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).

<SNIP>

			Frans


1.
Announcement of Docbook'ed & moved HIG:
http://lists.kde.org/?l=kde-usability&m=109345399523347&w=2

2.
Example of Implementation Note in HIG(scroll down a big)
http://usability.kde.org/hig/current/input-keyboard.php#input-keyboard-shortcuts