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

List:       kde-women
Subject:    Re: [Kde-women]Documentation: User/Code
From:       Eva Brucherseifer <eva () rt ! e-technik ! tu-darmstadt ! de>
Date:       2001-03-22 13:05:28
[Download RAW message or body]

Hi Lauri and all,

>
> Heh, maybe I should just post my "TODO" list, if you want a list of things
> we'd dearly love to have in KHelpCenter.
>
> Actually, this isn't too bad an idea, so I should clean it up and post it
> somewhere (and ask Mike McBride to do the same).
>

That sounds good, next week (I am at CeBIT this weekend) I will start a 
section "What can be done by KDE-Women?" with TODO lists, ideas what can be 
added, and a small howto on how to start with this.
Maybe Tink and Tina can add a list of their ideas about the zine as well.
Aga - do you want to write a list about what can be done regarding graphics?
And I will add some ideas about the coding/writing documentation section. 
Annma surely has more ideas about the coding, edutainment and other sections.
Anything I forgot?


>
> >  Well, two rules of thumb might hold for all kind of documentation:
> >  1.) Think about the target group!
> >  2.) When you document something written by yourself,
> >  never write documentation for yourself!
>

> One of the problems we have is that there is no one "target audience", KDE
> in general is equally as useful to developers and kernel hackers as it is
> to complete beginners.  Some applications this is more true of than others,
> and the ones that do have an obvious target market are very much simpler to
> write about.
>

I have to admit, that I nearly never looked into a manual to a KDE 
application. This is simply because they tend to explain only each feature 
and each dialog exclusively and only for this one application.

But one of the reasons I really love KDE is the workflow on the desktop. The 
applications go very good hand in hand, but this view gets lost in manuals.
The same is for source code documentation. People are only documenting 
isolated methods, but rarely the whole framework and the idea of the code. 
Unfortunately tools like doxygen and kdoc don't support the coder in 
describing the structur.

So regarding the user documentaion my idea is to have howtos for tasks 
describing how the workflow provided by the applications can be utilzed. 
These howtos can be on a very distinct level - for all the different users.

Some examples I have in mind:
- How to do a presentation with kpresenter?
   (how the background design for every page is done, some tips for good 
design,  which image format is good to include, tools for converting images, 
how big should the font be, which fonts are good, how to make a fullscreen 
presentation using a beamer....)
- How to write a thesis with latex or kword -> proplem of image formats, use 
of killustrator, including formulas, .... 
- how to develop a webpage
use of tools like quanta, kafka, webmaker,.. use of the konqueror 
(html-window+file-window+emacs), ...
- how to transfer a file from one computer to another, using the konqueror
(floppy, zip, CD, nfs, ftp, html, irc, mail, sftp...)
- how to get more fonts on your screen
- how to get mpegs from the internet onto a CD
...

The problem of good documentation is much more difficult. I don't understand 
why everyone is afraid of UML, it is so very simply, it is like a language 
containing 10 words... Unfortunately the guys doing kuml don't seem to 
progress very much. But maybe it is not the right approach since, because you 
have to do everything by hand. A more automated tool would be cool.

Extreme programming has another very interesting approach. They say, that you 
never should document methods or code. The code should be so clear that 
everyone understands. If there has to be a comment, the code is not ready 
yet. Instead they say, that whole classes should be documented, which is a 
bit like the howto approach I described for the user documentation. Describe 
the idea of a class, the meaning, the intension, the information flow, but 
don't get too much into the details. If the whole thing is clear, the detail 
can be understood with the context.
My experience when fixing bugs in kdevelop was, that the most difficult 
is,  to get the context and how the classes work together. The rest can be 
understood by simply reading the code (if the coders used good names for the 
variables and methods ;-)  ). And the guys never tell you anything - you have 
to learn it by yourself.

I don't see yet, what we can do about this in KDE-Women... right know it's 
mainly an idea of what can be improved. So I hope you are not too confused by 
my mindstorming :-)

bye, 
eva

PS: Laurie - sorry for the long email ;-)
Strange, but on the german lynn list the mails tend to be very long as well, 
must be a women thing...

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