Hi Andre,
On Wed, 2007-12-12 at 05:16 +0100, Andre Klapper wrote:
for a long time, several people have been unhappy with the current state
of the evolution user docs[1]. me too, but most of my rantings have been
on irc so i can't link to them. ;-)
when evolution 2.0 became an official part of GNOME 2.8, aaron was
working full-time on the evolution docs. now my impression is that
updates get written in a hurry without any proof-reading.
it has happened twice to me that svn changes have been overwritten[2,3],
because novell uses its own user documentation management for evolution
(read: apply changes to an adobe framemaker document and then try to get
them into svn. somehow). dropping code, instead of merging. cathedral,
instead of bazaar. that's not really how open source works.
it means that patches cannot get easily committed because they would get
overwritten by novell's next commit.
also, me and other folks have spent quite some time to discuss and
explain basic gnome doc workflow stuff to the assigned writers[4].
The doc team here uses Frame and it has only an export to xml and so
syncing from the commits/svn is no way possible, unless the frame is
modified manually. If there are any better alternative that can be used,
lemme know, I can try and propose to use for Evolution. Even otherwise,
we try our best not to overwrite any commits, instead we incorporate
them and do the commit. There were exceptions before, I hope that won't
continue. But, I'm open for alternative solutions if any.
the docs are still very novell-specific. red carpet is still
mentioned, for additional help you are told to visit
http://support.novell.com, sometimes it is Novellreg;
Evolutiontrade; and in general the documentation conventions haven't
been changed to gnome's conventions (markup[5], terminology).
also, lots of explanations are just of the read the interface back to
you type (but this is not an evolution specific problem).
when i translated the majority of the evolution user guide to german, i
have found a lot of errors[6]. some of them have been fixed, some of the
fixes have introduced new errors (did i say proof-reading already?).
summary: there are two problems. the modus operandi of novell's doc
team and the quality of the docs.
Quality of the docs is something, I can ensure that it would be done
properly.
proposals:
1) novell's doc team shall use the gnome svn version as the base version
for changes and rework the doc to follow gnome's conventions. novell,
like any other distributor, may of course derivate from the gnome svn
doc as they wish to provide their own, enhanced evolution user
documentation that provides a much better desktop experience with
novell's/(open)suse's desktop.
2) if we cannot find a consensus, fork. novell may have its own branch
for the docs, and we can port and backport changes between branches.
the gnome documentation team does not have enough manpower to update the
user documentation by itself, so i would still prefer to see the first
proposal happen. the question is whether we want to have a clean and
typo-free (but obsolete) doc, or a more-or-less up-to-date (but
error-prone and non-gnome-compliant) doc. having both
would be the best choice, of course.
I hope that we would find a way to solve it by the first proposal.
-Srini.
___
Evolution-hackers mailing list
Evolution-hackers@gnome.org
http://mail.gnome.org/mailman/listinfo/evolution-hackers
