[kde-guidelines] Licenses

[Frans Englich]

On Sunday 03 October 2004 17:23, zander at kde.org wrote:
> On Sun, Oct 03, 2004 at 04:03:18PM +0000, Frans Englich wrote:
> > On Friday 01 October 2004 10:56, Thomas Zander wrote:
<SNIP>
> > * The guidelines are not about technical issues. Understanding
> > programming/technical aspects should be handled elsewhere.
>
> Using that definition may limit our guides usefullness for programmers.
> We had some ideas, which are not clearly defined, so just ideas; that
> on the subject of (for example) the systray you want to have sections that
> describes:
> a) the usability conclusions (10 lines)
> b) the accessibility conclusions (maybe 15 lines)
> c) the reasoning behind those conclusions (2 pages)
> d) code examples and links to API docs
>
> Look at the test-website again; you'll note that whole items can be
> collapsed. 

Yes, I know about the CSS which hides/shows examples etc. It does make it 
better, but it doesn't affect the PDF/printed version.

> Point d) is one of those things that many people don't want to 
> see, but coders will really like those IMO.
>
> So, I think that (potentially large) code examples should really be present
> in certain parts of the UI.
>
> > * People shouldn't need it. All coding surrounding usability is simple
> > and involves only basic QT programming. What people need to know is
> > references, what classes to use, technologies(XMLGUI for example), and in
> > some cases specific functions(say, sizeHint). I don't see how a code
> > listing of basic class instantiating etc. would communicate that more
> > than a sentence.
>
> I disagree;  copy/pastable code is always good to publish if you point out
> one or more ways to do a certain thing.
> Don't forget that in order to make the guides something that the developers
> want to use you should not limit yourself to what the current guide already
> says.
> Consider this;
> a programmer wants to find out how to create a tooltip somewhere on his
> app. he could go to the API docs and guess which class can do this, or he
> could go to the guides where tooltips are discussed and find code examples
> plus links to the right API classes, after finding the
> usability/accessibility documentation, naturally :)  Which one would you
> like the programmer to reference?

I think we misunderstand each other; I don't mind discussing implementation, 
provide links to where it is discussed, links to the API reference, classes 
and so forth. But what I doubt is code listings, because I don't think it 
adds anything. 

If the reader gets to know what functions(particular ones) and classes to use, 
and links to technical aspects of them, what would an code listing add? For 
example, code doing anything typical with an arbitrary widget is obvious to 
the extent it can be assumed the reader has that coding competence. AFAICT, 
all such code listings would be similar and rather obvious(instantiate class, 
set some properties). The deep description is one click away, in the 
doxygen's @description field.


> > There are other resources for implementation and coding."
>
> Then you effectively made the developer go to the one resource he _needs_
> and he'll never reference the guides again.  A programmer has non desire to
> read usability guidelines.  

I don't think we can make developers read the HIG in that way -- if they want 
technical info they don't have to read the HIG to get it(and if they have to, 
it's bloated). What we can do is make it easy to understand how the 
guidelines is easily put in practice(and I think code listings doesn't add 
more than a describing paragraph).

This is typical this guidelines group :) -- discussing something that can be 
decided on a per case basis, and what really matters is content :) We can 
just drop this and have a look at each case when someone decides to actually 
write something :)

<SNIP>
> > However, if it's needed, I guess an mentioning at the beginning should be
> > ok(Docbook's legalnotice element). The Dive Into Python book has:
> >
> > "The example programs in this book are free software; you can
> > redistribute and/or modify them under the terms of the Python license as
> > published by the Python Software Foundation. A copy of the license is
> > included in Appendix H, Python license."
>
> I very much doubt that thats legal.

I'll read that book recommendation, and if necessary, contact the author. What 
makes you doubt it?


Cheers,

	Frans