[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-devel
Subject:    Re: KAutoConfig tutorial
From:       Benjamin Meyer <ben () meyerhome ! net>
Date:       2003-08-21 20:14:04
[Download RAW message or body]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

http://kaylee.meyerhome.net:83/~ben/kautoconfigdialog2/

> here's my hopefully constructive criticisms regarding style and
> methodology:

Very helpfull, exactly what I was looking for.

> in the introduction you state the purpose of KACD, that it makes creating
> config dialogs easier. but you don't summarize WHY it's easier. you then go
> on to list 6 bullet points that are purported benefits but don't explain
> WHY or HOW they are benefits.

Very good point.  Changed.

> and speaking of not understanding the technology, you really need to make
> the central concept behind KACD very obvious by stating it clearly and
> early: that it automatically links and syncs values in your configuration
> file with GUI items in the UI files. and that it does this by looking for
> widgets that have the same NAME as the keys in the configuration file. the
> fact that it gets the default values from the values as set in the UI file
> is also critically important to understand. i'd suggest you lay that out
> right away and then start showing examples.

Agreed, changed.

> as for laying things out, it might be an idea to try and visually separate
> the code from the text a bit more. i find it easier to read when there are
> clear visual separations. i usually use divs with a distinct colour and a
> hopefully tasteful border.

I have done that with all of the code now.

> in the simple example, including a link to the UI file and/or a screenshot
> of the interface would be nice.

As you state down before (and I relized) the first example doesn't add 
anythign and so I removed it.

> explaining what addPage does in a bit more explicit detail might be good,
> as well. the UI class is called General, and it's storing the settings in
> the General group... but... the General group of what? (the config file,
> right?) and is it significant that the name of the class is the same as the
> name of the config file group?

Nope, but that brings up a nice thing... Maybe it should!  :)  One less 
argument for developers to type in.  Should I change it now while I can still 
break binary compatibility and simply manually fix all of the existing kde 
apps that use it or add a new function or leave it the way it is?

> can i have it save into multiple groups from
> one UI class? how does manage that, or not?

Added.

> the line by line disection is nice, though i always struggle stylistically
> with them: do you put the description first and then show the code? or do
> you show the code then explain it? i usually waffle and tell the reader
> what they are about to see and why and then explain the details once
> they've seen the code. *shrug*

I put the explination below.  Seems just as good either way.

[snip]
> also write for timelessness. e.g. by writing: "These two classes are in CVS
> (kdelibs/kdeui and kdelibs/kdecore), but they will be released with KDE
> 3.2." you are dooming your tutorial to sound dated pretty quickly. try
> something like "These two classes are included in kdelibs/kdeui and
> kdelibs/kdecore starting with KDE 3.2." i'd probably also state which class
> is in which, and i'd also probably refer to libkdeui and libkdecore rather
> than their location in the kdelibs source tree as that's more useful for
> 3rd party developers. anyone who needs to know where the actual files are
> in kdelibs will know how to map libkdeui to kdelibs/kdeui =)

Changed.

> this is also information i'd include in the introduction rather than in the
> conclusion.

Yah.. , changed.

> you provide links to the documentation at the end, but you refer to the
> documentation several lines above. consider linking the reference to the
> documentation to the documentation directly.

Moved to the top.

> i'd also separate out the actual conclusion from the Behind The Scenes
> part.
>
> anyways.. .the above is just my little opinion and hopefully will be of
> help to you...

Very helpfull.  Can everyone take a look at the re-write and give me some more 
feedback?  Good enough to add to the developer.kde.org module?

- -Benjamin Meyer

- -- 
Public Key: http://www.csh.rit.edu/~benjamin/public_key.asc
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQE/RSgM1rZ3LTw38vIRApAuAKCzCpEK7BNSesZ2PjAL2o6UQjsuBQCeP8qK
LK/TGm+KP5qvV9u0444wEvw=
=+3iY
-----END PGP SIGNATURE-----

 
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<
[prev in list] [next in list] [prev in thread] [next in thread]