Documentation

[Robert Ratliff]

One suggestion:

1. Create a new page on the wiki, and paste in a chapter's worth or a
section's worth of documentation into the page. Save the page. Be sure
to refer to what version you're pasting in there as the "base version."

2. Then re-open the page for editing, make your changes, saving as you
go. These changes would represent the changes that you're suggesting the
developers make to the official (DocBook) documentation.

3. The wiki will keep track of the revision history. This gives two
benefits: for writers, it is easy to make changes, and for the
developers, they can use the wiki's history/comparison tools to figure
out what changes the person is suggesting, then migrate that to the
actual docbook.

Thoughts?

Also, for the "base version" in step (1) is there an easy way for
contributors to see the nightly HTML build of the gnucash-docs repository?

Robert

On 12/11/2013 3:29 PM, David T. 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.
>
>
> ________________________________ From: Frank H. Ellenberger
> <frank.h.ellenberger at gmail.com> To: David T. <sunfish62 at yahoo.com>;
> John Ralls <jralls at ceridwen.us> Cc: GnuCash development list
> <gnucash-devel at gnucash.org> Sent: Wednesday, December 11, 2013 11:37
> AM Subject: Re: Documentation
>
>
> Hi David,
>
> Am 11.12.2013 19:22, schrieb David T.:
>> John—
>>
>> I’ll note that the GnuCash website Writing Documentation page, and
>> it still includes all the information that scared David C. away (me
>> too, I’ll add). Moreover, the directions there are all svn-based.
>> Is there a clear and simple outline of the git process for
>> documentation that us non-programmers can daily follow?
>
> You could also try this: Install Eclipse from eclipse.org - it is
> java based. Inside install the following plugins: EGit for git
> access VEX, a visual XML editor optional CDT, the C Developement
> Tools, to run the autotools - make etc. - inside Eclipse.
>
> Help us to improve the related wiki pages: GIT, Eclipse, ... by
> reporting the problems occuring in a fresh install. Ask here or
> quicker on IRC
>
>
> To date, I have avoided the
>> DocBook cycle in favor of placing my corrections into comments on
>> Bugzilla and relied on others to migrate my edits into the actual
>> documentation. If there really were a simple method for editing,
>> that functions more like a word processor rather than a
>> programming platform, it might broaden the documentation team.
>>
>> David
>>
>
> ~Frank _______________________________________________ gnucash-devel
> mailing list gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>

-- 
Robert Ratliff
blog: http://bobbyratliff.nfshost.com/
github: rratliff