Thomas Zander wrote:

 
> Bottom line; the file format is open, but maybe that needs to be made a
> bit more public at sites like www.koffice.org
> the example application KPresenter needs some finish, you are right.
> Documentation is not something the coders are concerned with, the writers
> are
> working on the docs.  Its not finished; thats correct; blame us for
> releasing too early too often.
> 
> KOffice is evolving; and with a team of about 4-10 people I think they are
> not doing a bad job.

I've been wondering how to answer the challenges ESR set us here.  I can't 
comment on the file formats I don't know enough, and I actually agree with 
most of the rest.  KPresenter's UI is just... dense and overwhelming.  And 
the documentation as released with 1.1.1, well, it was absolutely 
appalling.  

However...

I think the developers are also labouring under a misunderstanding on the 
state of documentation.  4-10 people, that's more people than the entire 
active documentation team for all of KDE.  Go take a look at the current 
docs status on http://i18n.kde.org/doc/current.html , realise I'm being 
very generous marking some of those up to date, and then look at how many 
say "Not maintained".  Not maintained pretty much means I look after it 
myself, or anyone else I can nag into helping in the short term, and I'm 
getting spread really thin here.

I agree that experienced writers often do a better job documenting things 
than a developer, but I don't think the existence of a documentation team 
should absolve the developers from ever writing any documentation, or 
allows you to be "unconcerned" with the documentation.  

Note, most of our writers are not at all experienced, and probably 90% of 
the people who approach me about writing are doing it because we can't code 
(and they quit when they learn how to code!) It's also true that something 
over 90% of those people never end up writing a line of documentation, 
since writing is a whole lot harder than it looks, and since we want good 
documentation in preference to just lots of it, I can be quite a hard 
taskmaster.

Enough whining, KPresenter recently gained a new documentation maintainer 
after having been abandoned for well over a year, maybe closer to two.  
He's doing a great job, but we really are playing catchup here.  Since 
there is so much to do, we've had to prioritise, and so the order of 
business is

1: Fill in all the blanks, the things that are entirely undocumented (we're 
nearly there now)
2: Improve the existing things (like the tutorial) because they are pretty 
sorry compared to the actual state of KPresenter (some of the worst of it 
is cleared up.. the confusing colour references as Cathy stated are not, 
I'm going to take a look at that myself, right now)
3: If there is any time, between frequent releases, massive interface 
changes, and the writer having a day job, we'll try to polish the result of 
1 and 2 into a more professional state.       

Have the rest of you on koffice@ actually looked at the documentation 
lately?  Only KWord and KPresenter really have any, and KSpread is another 
that's been out in the cold for a long time (and in fact, that too was 
picked up just yesterday by one of our very best and most dedicated 
writers, so we should expect major updates there in the medium-term.)  The 
docs for Kontour don't even relate remotely to the application as it is 
now, in fact I think i'll remove them, they're more confusing than useful.  
Kivio has none, and isn't going to get any.  Kugar, oddly, is very well 
documented from a technical standpoint, but some actual usage examples 
would probably see this app getting more real world use.

These are *enormous* applications, and documenting just the interface is an 
enormous job, it's boring to do, and it's pretty boring to read.  Getting 
the interface documented is the absolute bare minimum criteria for a "User 
Manual", and some real usage examples, and a greatly improved tutorial are 
much more useful to the end-user.

I'm not going to demand that you all drop the code and start writing docs, I 
know that isn't going to happen.  As tempting as it is, nobody will go for 
it if I start to demand that applications without documentation don't get 
shipped :)  

All I'm saying is, it wouldn't kill you guys to just look at the 
documentation now and then, and maybe write a few lines, or make some notes 
for the people who are doing the writing.  If you don't want to write 
docbook, then don't, write your text inside a comment block or in a 
separate text file, or just mail it to me or the maintainer if it has one.  
Don't dare use "I don't know docbook" as an excuse, it won't fly.  Don't 
use "I don't speak great English" as an excuse, that won't fly either.  

Maybe it's going to take me being an unrelenting nag, until you all are sick 
to death of seeing mail from me (as one person puts it on IRC, I'll be a 
documinatrix).  I don't really care what you think of me, what I do care 
about is that KPresenter, and every other KDE and KOffice application, will 
one day have user documentation that we can all be really proud of.

Regards
-- 
Lauri Watts
KDE Documentation Coordinator