Confirming that no one else is working on Guide Documentation, Chapter 3

Tommy Trussell tommy.trussell at gmail.com
Tue Jul 27 19:39:35 EDT 2010


On Mon, Jul 26, 2010 at 11:27 AM, Thomas Bullock <tbullock at nd.edu> wrote:
> Thanks for your offer to review drafts of documentation changes. What is the customary way of
> Handling that?  I would not want to send a draft to the devel list, lest it be confused as a patch.
> Or should that concern be handled by bold identification that the attached is a draft and not
> A final proposed patch?

As far as customary goes, I am getting the idea that your predecessors
have experimented and improvised as they went along. I'm going to
suggest two options and you can pick and choose or suggest another
option. In a nutshell, I think you can

1) Create a patch and file it in bugzilla
   and/or
2) Publish an html version people can review

I just looked at
http://svn.gnucash.org/trac/browser/gnucash-docs/trunk/HACKING and of
the things it says I think the most careful way would be to create a
patch file (using diff) and file it as a documentation bug in
bugzilla.gnome.org. (Alternatively you could post the entire updated
file but a patch would make it clearer exactly where your changes
are.)

For example, once you revise a section then you could create a patch
against trunk in svn and post the patch as a documentation bug against
gnucash in bugzilla.gnome.org (identifying the particular patch as a
draft you want people to review).

If I want to review your patch I could copy the documentation trunk to
my local machine and download and apply the patch to the local files
and have a look. I can then make my comments to the bug in bugzilla.

I think there are some advantages to this procedure. There haven't
apparently been many documentation patches in bugzilla, but I found a
couple examples so you can see. For example
https://bugzilla.gnome.org/show_bug.cgi?id=568244 Note that you can
view the patch as a diff and see the exact changes in context. To me
that might make it worth the effort of creating the patch and the bug
report.

(The HACKING doc also suggests posting patches to the gnucash-patches
mailing list. I haven't subscribed to that list, however, and it seems
like bugzilla might have some advantages.)

Since you can alternatively output HTML as described in
http://svn.gnucash.org/trac/browser/gnucash-docs/trunk/README you
could post the draft to a public site (a free one such as google sites
or google docs would probably do) and invite comments by posting a
notice on the developer's list and include the url there and in the
bug report. I think the reviewers can most efficiently make their
comments in bugzilla.

P.S.: Whatever you decide to do I think an explicit procedure should
go in the wiki and/or the source files so we can point people to it.


More information about the gnucash-devel mailing list