Qt.Py extention and modification guide
This document helps you to :
General
__FIXME__, I'm only a cut&past of a text-document ...
    
Guidelines for extending and manupulating the portal
====================================================


General
-------

o First of all, keep it easy and beautiful (which at least means non-ugly).
o Keep it functional.
o Keep it consistent.
o If you are in doubt, don't do it.

  A summary of all above :

o Do it the python way.



Layout
------

o Try to see the "invisible lines" going all through the site.
  Virtually everything is aligned to them. 
o If you add your own stuff, align it to these lines, too.
o If you add your own stuff, look if a similar problem exists
  already. If yes, do it the same way. If you think your solution
  is superior, change all occurances to your solution.
o Test your modification at least with IE, Mozilla and Konqueror
  (as we're doing KDE/Qt products, the last point is a must). 
  Opera support seems to be broken for now.
o Remember what screen resolutions are used today. Currently it runs
  nice with 1024x768 and above. 800x600 is in "compatibility mode",
  the sf-logo won't be displayed there
o Every href, which is not a link to an internal html-page, should be
  clearly described so. Best way to do this is by a little icon or the
  text "external" if it leaves the site.
o Try to understand what a "pull" and a "push" modell is. Pull means,
  you give the user the choice to pull information he needs, push means
  you give the user the information you think he needs. Pull-modell will
  (almost) always be preferrably.



Logic
-----

o The basical logic currently used is 3x3. Which means three nodes on the top,
  with a maximal depth of three. The topnodes currently are (as sense of)
  "see it", "touch it", "talk about it". Depth "3" means : The maximal number
  of enumerations this site could have is x.y.z. Where x is the number of major
  nodes (three per definition). Each x may have unlimited y, and each y may have
  unlimited z. Each 'z' *should* really not have any subnodes or links, EXCEPT 
  a file-object to download or a link to something external. Anyway, try to
  avoid the exceptions as much as you can. In other words : Try to give a 
  solution after two clicks.


  Again, these rules have been chossen for easines. Out of
  ergonomical reasons, it is prooved that subnodes are worse than large documents.
  So better make large, clearly structured documents than a labyrinth of nodes, 
  "click here for page 2"-links or anything else that requires unnecessary user
  interaction.



Documents and Text in General
-----------------------------

o First one point which I really want you to remeber :

  Forget about any myth you've heard about "n00bs", "experienced 
  users" or "cracks" in any relation *except* their very special 
  kind of knowledge. 
  So if you make a homepage (or anything else) for
  ueber-kernel-hackers, don't assume they know the same about their
  browsers as they know about interrupt-controllers. If you only have 
  the smallest doubt about something being unclear, write some short, 
  clear and non-arrogant sentences about it. Many readers/users will 
  appreciate it. 
  There *are* cultural and educational differences between everyone.
 

o Give a clear subject that describes about what this document is about.
  The carefully choosen words in the subjects should reflect the intended
  audience. 

  "How to create your first PyQt program"

   will have other readers than

  "Extending sip classes for incorporation of new kde-widgets"


o within headlines and links, write the most important things first.
  Only prefix them with words shorter than 3 letters (a, an, the):

  "a html-gpg-signing application"

   not
  

  "an application for html-gpg-signing"


   or worse

  "an cool application to sign html documents"


   or worst
 
  "check this out"

o Make easy sentences and use clear, carefully choosen words. Don't
  over-complicate easy things. If you have a chance to express your words
  with a good picure, do it. (But keep in mind image size too). Also, don't
  forget to give your pictures (or information boxes) clear titles. Like

  "Img. 5 : Improved button-labels on the right."

   not

  "Img. 5 : Looks better now." 
 


  According to the dpa (german press agenture) the
  ideal length for understanding of a sentence is 9 words. Up to 15 is in
  general ok too.
  Everything above this isn't bad, but tends to be complicated. Some sentences
  will require 30+ words, which is also accepable, if its necessary.


o When you've finished your work, sleep a night. Then re-read it. While doing so,
  try to think about a reader who's hearing music, talking to a colleague and
  eating something. Will he understand it ?

  Give it to a friend, or post it to the mailing list. If you're getting 
  critisied, listen carefully and figure out which points are relevant and
  should be improved.
  


    
Fig. 1 : __FIXME__ : html-alzie me
References
(c) 2002, Marc Schmitt