[kde-guidelines] Licenses

[zander at kde.org]

On Sun, Oct 03, 2004 at 04:03:18PM +0000, Frans Englich wrote:
> On Friday 01 October 2004 10:56, Thomas Zander wrote:
> > My first thought on this reflects a discussion (for a book) I had some
> > time ago; the concern here is that code-snippets should be libarally
> > licensed; people should be completely free to copy code from the guide,
> > and do anything with that code. This in contrast to the texts themselves.
> >
> > If it is not practical to change the licensing mid-page, I suggest to
> > publish source-code twice. One time in the book; and one time as seperate
> > files which will be downloadable (or shipped on a CD).  The copyright
> > holder of that code should then allow us to distribute his code in 2
> > licenses, one is the one of the paragraph it appears in, the other is the
> > very-liberal use-wherever-you want license.
> 
> But the guidelines shouldn't contain large code snippets, AFAICT, because:
> 
> * 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. 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?

> For editing-guidelines I started to write, it said:
> "Don't do code listings in Implementation Notes. These Guidelines are for 
> usability and not implementation.

You can't seperate those...

> 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.  Thats the cold/hard reality.

> 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.

-- 
Thomas Zander
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://mail.kde.org/pipermail/kde-guidelines/attachments/20041003/38004fa7/attachment.pgp