Documentation Processing Ideas
tbullock at nd.edu
Thu Aug 5 07:52:51 EDT 2010
Geert, John, and all the others who have been supporting my effort by your helpful answers,
Thank you! You are welcome for your thanks that I am starting on documentation. I will try to live up to your trust that my effort will actually result in something that is useful to GC users. It seems to me that there is still much to learn just to put me in position to make a contribution that others can use.
Your SVN log instructions are just what I need to access its information, both in a terminal and in a gui.
Using a wiki for interim staging of information will also take some time as I learn the structure and process of building and modifying wiki pages and integrating them into the Gnucash set of pages.
From: Geert Janssens [mailto:janssens-geert at telenet.be]
Sent: Wednesday, August 04, 2010 2:13 PM
To: gnucash-devel at gnucash.org
Cc: Thomas Bullock; John Ralls
Subject: Re: Documentation Processing Ideas
On Wednesday 4 August 2010, Thomas Bullock wrote:
> [<<Tom>>: ] Thanks John, for your clear and relevant comments and
> instructions. Also, daunting, I must say!!
> First, how do I access the SVN log? Is that a separate file or part of the
> download process when I use the SVN CHECKOUT process? Whether it will be
> helpful or not won't be known until I read it. For practical purposes I
> need to examine the range of changes from 2.0.0 to present. Since
> documentation has not been kept up, I assume that I would have to look at
> the Code log as well as the documentation log. So I guess that means 2
> SVN logs.
On the command line, you can call "svn log" in the directory of which you want
to see the logs. Note that this will cause a very long listing though.
There is also a web interface to these logs. You may find that easier to use:
This page is an online view of the subversion repository. You can navigate up
and down the source and documentation tree here. On the right side of the page
you have a link: "Revision Log", which, when clicked, will give you the svn
revision log for the directory you are in.
Note that the log command and the "Revision Log" link both work recursively.
So if you use it in a certain directory, it will give you a list of all
revisions in that directory AND its subdirectories (which is useful in my
> Second, however I get the information, I think the most urgent need is to
> document installed working features that have not yet been disclosed
> [meaning in the documentation, even though such features could have been
> issues of discussion in the user and developers lists] describing first
> their purpose then how to use them. That could be a list in itself, only
> to be brought into focus by research and the contributions of system users
> and developers. Later on, once this is caught up, it makes sense to me to
> systematically test every bell and whistle to find out whether documented
> and, if so, does it work as described.
That makes sense.
> Third, the idea of a wiki page is good. The present limitation is that I
> need to learn how to create and use such a tool. The wiki allows
> flexibility for many people to add ideas as the ideas appear to them.
Yes, working with a wiki or xml differs from working with a typical word
processor. The key difference to remember is that wiki/xml markup focuses on
the document structure (you define chapters, sections, subsections,
paragraphs,...) instead of presentation (the layout is defined in completely
separate files, usually css).
Typical use of a word processor has this blurred a bit. It mixes content and
presentation with less focus on the document structure. This is good for
simple, relatively small documents, but less so for big, complex ones. (Note
that you *can* have a structure focused workflow with a word processor, but
most people don't do or know how to do this.)
Good directories to run the log command (or click the "Revision Log" link)
gnucash/trunk: this will give you the logs for all code changes
gnucash-docs/trunk: this will give you the logs for all documentation changes
> Fourth, my thought is to stay focused on the Guide. Once it is better,
> then focus could shift to Help. Is that reasonable?
> Fifth, there is a dimension to the documentation process that is time
> consuming. I am toying with the idea that some kind of documentation is
> better than none. Using a wiki as an INTERIM step to getting missing
> documentation available quickly may permit covering more ground sooner
> than going the extra mile to integrate everything into the Guide and Help
> manuals right at the beginning. Do you think that idea would be accepted
> even though not the preferred and final solution?
I would agree.
Let me put it this way: GnuCash is a volunteer project. I think any positive
contribution is welcomed. From my point of view, any documentation that gets
added is a positive contribution. The format (wiki or guide) is secondary in
I think in the long run having a more complete guide is certainly desirable,
but adding documentation snippets in the wiki to have more documentation
available in the short term is very welcome as well. The wiki could (partly)
serve as an incubation area for the guide.
BTW, I'm really happy you are working on the documention. Thanks for that !
More information about the gnucash-devel