From kde-core-devel Thu Aug 26 03:59:30 2004 From: Frans Englich Date: Thu, 26 Aug 2004 03:59:30 +0000 To: kde-core-devel Subject: Re: KDE Doc: Content of the HIG Message-Id: <200408260359.30877.frans.englich () telia ! com> X-MARC-Message: https://marc.info/?l=kde-core-devel&m=109349440410010 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/ > 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). 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