KDE Doc: We need meta-HIG

[Frans Englich]

On Wednesday 25 August 2004 13:20, Aaron Seigo wrote:

(Big pardons for this flood of lengthy mails, but I try to get my sketchy 
ideas out to avoid race conditions/conflicts later on. The maintainers have 
probably already thought about what I mention; all I know is the aKademy 
people/non-KDE lists folks have done is the top mail and planetkde.org, no 
vids yet and incomplete listening of audio -- but I have a hard time 
appreciating something else more)


As we know, what the HIG is and what it's not, what goes in and what goes out,  
must be well defined. We also need to document this in order to sustain 
consistency over time, and distribute maintainer burden. I'm not talking 
about a Docbook :), but a simple HTML document. I started on a plain text 
file when I fixed the current HIG; I think it's a starting point:
www/areas/usability/hig/src/GUIDELINES
(some of it conflicts with the top mail)

We also need to make it clear that:

* The HIG will be used for in-house development, but should be applicable for 
3rd parties. In other words, it should be genericly written, and dictate the 
"KDE style", while things specific to the KDE project should be elsewhere(KDE 
Policies, KUA). I can't remember what, but I've found issues which would make 
such a paragraph relevant (assuming that is our intentsions with the HIG)

* (closely related to above) Torsten quotes future guidelines:
"Icon design both affects and is influenced by technology as well as 
usability, beauty, fashion and marketing. This aspect is important for the 
choice of a default icon style and it needs to be carefully evaluated during 
the design process of each particular icon."
We need to have a clear view of whom our readers are. Who and why will read 
the guidelines? Is the selection of icon theme for KDE relevant for the 
readers, or KDE maintainers? Is it of interest?

* What we emphasize and encourage is what people do. Above Torsten emphasizes 
it needs to look fancy; do we need more bells and whistles in KDE? Wouldn't 
it be better if did a small lie and said "only focus on usability"(we tend to 
get the bells and whistles in either case, here in KDE)

* Before someone throws this lovely subject for open debate(tabs vs spaces 
with little sleep and too much booze, eh?): If we decide to have a coding 
style(XML indenting) for these projects, I suggest it is 4 spaces. Why 4? 
Only silly reasons: 1) I said it first, and that's an easy way to solve the 
conflict; 2) It's the middle between zero spaces and a tab; 3) The current 
HIG and KUA uses it. (anyone who have read my code knows I prefer tabs). Of 
course, good luck reaching a consensus in open discussion. We could insert 
editor tags at the end of files.

* A lot of more things, but my memory currently fails me.


Technical issues:

* We in the KDE project do a lot of Docbook circus; I think we would make use 
of W3C XML XSD instead SGML DTD, especially in the long run. I think we will 
switch to XSD sooner or later(because it's simply being XML and that SGML is 
dying, and XSD is better)[1], and we should pick a time when that switch is 
most strategic. We will have a handful of projects popping up now, and now is 
suitable to add a parallel XSD system, for usage by these projects and the 
writing of new app documentation. Existing documents can then be gradually 
converted or everything "overhauled"(easily scripted), whatever we feel for. 
We should also remember that KDE 4.0 is suitable for large moves. 
xmllint(used by meinproc/checkXML) support it and Docbook schemas are 
available. I don't think it's a question of if, but rather when, and now is a 
good time to make sure it not become a limitation later on, but that KDE has 
extra power and flexibility right now. Lauri, I bet you have something to say 
on this.

* We should use XInclude instead of system entities(and preferrably add a 
namespace tag to kdex.dtd if we don't use XSD)


			Frans


1.
XSD vs DTD: Quick googling returned(haven't read it):
http://www.sitepoint.com/print/xml-dtds-xml-schema
http://www.adp-gmbh.ch/xml/schema_vs_dtd.html
http://66.102.9.104/search?q=cache:ciPq4ywI7_4J:www.idealliance.org/papers/xml02/slides/kennedy/kennedy2.ppt+dtd+vs+xsd&hl=en&ie=UTF-8