Re: [Evolution-hackers] future of evolution user docs.
Andre, On Thu, 2007-12-13 at 01:23 +0100, Andre Klapper wrote: > Am Mittwoch, den 12.12.2007, 13:58 -0500 schrieb Matthew Barnes: > > On Wed, 2007-12-12 at 23:21 +0530, Srinivasa Ragavan wrote: > > > Frame files are the master copies here. > > the master copy should be in svn, in a format that i can open && edit. > having it in on someone's personal computer in some company is not my > understanding of community software. > > > > You think committing Frame files to svn would solve it? If so, I would > > > be happy to do that. > > if novell buys a framemaker copy for every contributor who wants to edit > the evolution user docs, i can live with that workaround. ;-) > seriously: it won't solve your problem that any changes have to be > manually "backported" from the svn version to novell's file, and i guess > that could become a lot of work. I said that but I didn't mean it ;-). > > > > I'm open to propose a new tool to the doc team here for Evolution if > > > any. Definitely hand editing the entire doc file isn't going to be > > > easy. > > Agreed. I'm a bit out of my element here. Maybe Andre can chime in > > with some suggestions. What tools does the GNOME documentation team > > use? Surely we're beyond hand-editing XML files (/me hopes). > > > > Here's a few possibilities, but I don't much about them: > > http://wiki.docbook.org/topic/DocBookAuthoringTools > > i'm also not a doc writer, i only know of emacs users, and that's most > likely not an option here. i've already asked for feedback on the > gnome-doc-list, but srini may of course also blog about it (we're so > web2.0y, aren't we?), explaining the issue and asking doc writers for > feedback...? > Sure, I would do that. -Srini ___ Evolution-hackers mailing list Evolution-hackers@gnome.org http://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] future of evolution user docs.
Am Mittwoch, den 12.12.2007, 13:58 -0500 schrieb Matthew Barnes: > On Wed, 2007-12-12 at 23:21 +0530, Srinivasa Ragavan wrote: > > Frame files are the master copies here. the master copy should be in svn, in a format that i can open && edit. having it in on someone's personal computer in some company is not my understanding of community software. > > You think committing Frame files to svn would solve it? If so, I would > > be happy to do that. if novell buys a framemaker copy for every contributor who wants to edit the evolution user docs, i can live with that workaround. ;-) seriously: it won't solve your problem that any changes have to be manually "backported" from the svn version to novell's file, and i guess that could become a lot of work. > > I'm open to propose a new tool to the doc team here for Evolution if > > any. Definitely hand editing the entire doc file isn't going to be > > easy. > Agreed. I'm a bit out of my element here. Maybe Andre can chime in > with some suggestions. What tools does the GNOME documentation team > use? Surely we're beyond hand-editing XML files (/me hopes). > > Here's a few possibilities, but I don't much about them: > http://wiki.docbook.org/topic/DocBookAuthoringTools i'm also not a doc writer, i only know of emacs users, and that's most likely not an option here. i've already asked for feedback on the gnome-doc-list, but srini may of course also blog about it (we're so web2.0y, aren't we?), explaining the issue and asking doc writers for feedback...? andre -- mailto:[EMAIL PROTECTED] | failed http://www.iomc.de/ signature.asc Description: Dies ist ein digital signierter Nachrichtenteil ___ Evolution-hackers mailing list Evolution-hackers@gnome.org http://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] future of evolution user docs.
On Wed, 2007-12-12 at 23:21 +0530, Srinivasa Ragavan wrote: > Frame files are the master copies here. I think that should change if at all possible. > You think committing Frame files to svn would solve it? If so, I would > be happy to do that. The preferred work flow should be to import the DocBook sources into FrameMaker (or whatever), make changes, and commit changes back to the DocBook sources. Ideally, there should be no need for intermediate files like Frame files. If that's just not feasible with FrameMaker then adding the Frame file to SVN would at least help resolve the perception that Novell is keeping an iron grip over the Evolution documentation. But I think that should be a temporary measure until a more DocBook-friendly tool can be found. > I'm open to propose a new tool to the doc team here for Evolution if > any. Definitely hand editing the entire doc file isn't going to be > easy. Maintaining 7500 lines file, with so many pages, images etc > isn't going to be easy. Every release we do many features and fix so > many bugs, that would cause approximately 500-1000 lines of > corrections. Manual editing isn't feasible. It would create more > troubles than before. Agreed. I'm a bit out of my element here. Maybe Andre can chime in with some suggestions. What tools does the GNOME documentation team use? Surely we're beyond hand-editing XML files (/me hopes). Here's a few possibilities, but I don't much about them: http://wiki.docbook.org/topic/DocBookAuthoringTools Matthew Barnes ___ Evolution-hackers mailing list Evolution-hackers@gnome.org http://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] future of evolution user docs.
On Wed, 2007-12-12 at 11:32 -0500, Matthew Barnes wrote: > On Wed, 2007-12-12 at 17:00 +0530, Srinivasa Ragavan wrote: > > 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. > > I think the core issue here is what is considered the "master" copy of > the documentation. This being an open-source project, the master copy > *should* be the DocBook sources in GNOME Subversion. It sounds to me > like the master copy is some proprietary-formatted document locked away > inside Novell. This creates a bottleneck for community contributions to > the documentation. Approved patches should not have to flow through a > single gatekeeper. > > I don't care what tool we use to maintain the docs but the work flow > should be similar to any other source code change: checkout or import > the master copy from Subversion, make your changes, and merge them back > into the master copy. If FrameMaker is not conducive to that kind of > work flow then we should look for a different tool, even if that means > editing DocBook sources by hand. Frame files are the master copies here. You think committing Frame files to svn would solve it? If so, I would be happy to do that. I'm open to propose a new tool to the doc team here for Evolution if any. Definitely hand editing the entire doc file isn't going to be easy. Maintaining 7500 lines file, with so many pages, images etc isn't going to be easy. Every release we do many features and fix so many bugs, that would cause approximately 500-1000 lines of corrections. Manual editing isn't feasible. It would create more troubles than before. -Srini ___ Evolution-hackers mailing list Evolution-hackers@gnome.org http://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] future of evolution user docs.
On Wed, 2007-12-12 at 17:00 +0530, Srinivasa Ragavan wrote: > 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. I think the core issue here is what is considered the "master" copy of the documentation. This being an open-source project, the master copy *should* be the DocBook sources in GNOME Subversion. It sounds to me like the master copy is some proprietary-formatted document locked away inside Novell. This creates a bottleneck for community contributions to the documentation. Approved patches should not have to flow through a single gatekeeper. I don't care what tool we use to maintain the docs but the work flow should be similar to any other source code change: checkout or import the master copy from Subversion, make your changes, and merge them back into the master copy. If FrameMaker is not conducive to that kind of work flow then we should look for a different tool, even if that means editing DocBook sources by hand. Matthew Barnes ___ Evolution-hackers mailing list Evolution-hackers@gnome.org http://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] future of evolution user docs.
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. ___ Evolution-hackers mailing list Evolution-hackers@gnome.org http://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] Post-release version incrementing
> Tor, > It may not work out here, since the micro version is what we bump during > release which is in sync with the GNOME Release micro version. I sent the idea to desktop-devel-list and gtk-devel-list instead, as mbarnes suggested. Let's see if anything comes out of it. Some people seem to like the idea, others don't see the point. In any case, if some change in convention happens, it presumably won't be in the current development cycle. --tml ___ Evolution-hackers mailing list Evolution-hackers@gnome.org http://mail.gnome.org/mailman/listinfo/evolution-hackers
