Documentation

David T. sunfish62 at yahoo.com
Thu Dec 12 19:50:47 EST 2013


From: John Ralls <jralls at ceridwen.us>
To: David T. <sunfish62 at yahoo.com> 
Cc: Frank H. Ellenberger <frank.h.ellenberger at gmail.com>; GnuCash development list <gnucash-devel at gnucash.org> 
Sent: Wednesday, December 11, 2013 7:47 PM
Subject: Re: Documentation
 




On Dec 11, 2013, at 1:29 PM, David T. <sunfish62 at yahoo.com> wrote:

Um, yeah. My point is that the developer pool would like help with documentation, and most users would be happy to do that, if it matched their mental model on how to edit documents. For most of us (even more advanced types with years of professional editing experience), that model is more based on the word processing editing model rather than the programmer's version control system. Installing Eclipse, and then spending time installing the add-ins, and then on top of all that learning how to use it, is much more complicated than opening a file in a Word processor, turning on "Track Changes," typing in your replacement text and sending it in for review.
>
>
>As wonderful as version control systems might be (and I am sure they really are), there is (for me at least) one hell of a learning curve--one that precludes my being much more than a commenter on Bugzilla bugs for documentation.
>
>
>David
>
>
>P.S.: Over the years, I have installed Eclipse at different times on different platforms in the (clearly misguided) hope that I might learn how it works. Thus far, it has eluded my abilities to understand. Similarly, I earlier today followed John's instructions elsewhere on this thread, and installed TortoiseGit and Git for Windows, but was unable to find an entry point to editing the GnuCash documents that made any sense to me.

Yup, got that.

So having cloned the gnucash-docs repo with TortoiseGit, you have the baseline files on your computer. The next step is to open either gnucash-guide.xml or gnucash-help.xml in such a way that you can edit it without having the XML bother you too much. That's actually the hard part. You could use PanDoc to create a M$Word or OpenOffice document and make your edits, but I haven't yet seen a good way to then put it back into DocBook format to make a commit with. 

I'm leaning towards the wiki solution at the moment.

Regards,
John Ralls

John--
I have moved the bar ever so slightly: I see that I can browse the Branch Files and view the XML content of the guide. So somehow, I actually have gotten the source onto my own computer.

Actually editing stuff is another thing altogether. The "files" don't exist as such on the disk, so (apparently) one is supposed to get into them somehow through git. I haven't figured that part out; there isn't a "File->Open" that I can see.

Moreover, I see your point about the XML. It makes the head hurt trying to decode it all in your brain on the fly. 

David


More information about the gnucash-devel mailing list