Re: quo vadis, docs (a rant)

[Stefan Skoglund <stetson bredband net>]

mån 2009-02-09 klockan 12:43 -0500 skrev Tristan Van Berkom:
> Luis do you write software ?
> 
> Not that its important that you do, but just to clarify the issue;
> "simply asking what does this dialog mean" in the long run usually means:
>    - Take a screen shot of the dialog
>    - Open the html or whatever the docs are written in
>    - take time to format the docs/text/images in a readable way
>    - take time to properly describe your feature or functionality
>    - take time to write a healthy ChangeLog entry for your
>      docs commit.

Maybe he does and maybe not, i don't know  but isn't it a truth that
many of the programs and applets and so on in 'gnome core' is pretty
small programs (afterall the numbers of main developers in each project
is pretty small.)
An coherent description in plain written english or swedish in my case
is always a good supprt for the designer and that is also a strong base
for working  and useful user documentation, so what am i saying:

first an idea
second: try to write an simple user documentation for your own usage and
while doing that thinking over the problem : does this work ? or should
i be doing it some way another because i can't describe my idea in an
understandable way ?
third: if possible do a mockup which matches the doc and send that
includig the doc to interested UI people, or  test the mockup and read
the documentation yourself. 
NOW do the real program while observing the previously created
documentation because that is your most important design tool.

I can't help thinking that the problems with glib and its object system
which newly-minted gnome developers have is because maybe the designers
didn't wrote these documents first.
I have Matthias Warkus GNOME-book at home and in this book is an example
of using multiple inheritance in a media player, personally i think his
example is broken and so is a bad reason for allowing MI.

This problem (no good documentation of how to use something) is also a
reason why the project is deprecating bonobo, the only ones which know
that is i think the evolution devs.

Nah, i think i will stop ranting.