Fwd: Suggestion: make conformance criterias clear

[Celeste Lyn Paul]

Forwarded from Frans, he has had trouble sending mail to the lists?  

----------  Forwarded Message  ----------

Subject: Suggestion: make conformance criterias clear
Date: Sunday 08 October 2006 12:46
From: Frans Englich <englich at kde.org>
To: kde-guidelines at kde.org

Hi everyone,

As you well are aware, I am not involved in the HIG writing process, but I
have here a comment that I take the liberty to believe can be useful for
those who are:

While conformance testing and being involved with creating W3C's XQuery
language, I've reached the conclusion, as other as well has, that the clearer
what's right and wrong is, the better. For example, if a specification
consists of large paragraphs of exotic, academic prose, readers will have a
harder time grasping it (properly).

I'm not writing this to urge editors to write in a simple, non-complex,
compact style, but that it might be an idea to formalize HIG-"conformance" a
bit.

Of course, in some cases the HIG is only "guidelines" and suggestions, but in
other cases it indeed is clear instructions for how things should and
shouldn't be. The more exact instructions the HIG has, the better. Also, of
course, one want those instructions to be communicated as clear as possible.

This makes me suggest that sections can exist of initially
 paragraphs("prose") followed by a list of very brief conformance
 requirements. They would have short identifiers, like "HIG-Comboboxes-1",
 "HIG-Comboboxes-2" and so on, and possibly be appropriately styled. An
 appendix could summarize all the conformance requirements in the document.

I believe this would appeal to programmers and others who are actually going
to read it and adapt programs to it. Instead of hundreds of pages
of "babbling" paragraphs, the reader would have a clear indication of what
needs to be done and what remains to be done. One could take one conformance
point and look through the whole program, then the next, etc. A bit like test
cases or bug reports, if you like.

Anyway, this suggestion appears relatively late and all that, but here it
neverthless is.


Cheers,

		Frans

-------------------------------------------------------

-------------------------------------------------------

-- 
Celeste Lyn Paul
KDE Usability Project
usability.kde.org