Re: [Evolution-hackers] future of evolution user docs.

[Srinivasa Ragavan <sragavan novell com>]

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 "Novell®
> Evolution™" 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.