[prev in list] [next in list] [prev in thread] [next in thread]
List: koffice
Subject: Re: Question about your KPresenter's review
From: Lauri Watts <lauri () physos ! org>
Date: 2002-02-10 14:57:47
[Download RAW message or body]
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
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic