Documentation Processing Ideas

[Geert Janssens]

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:
http://svn.gnucash.org/trac/browser

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 
opinion).

> 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) 
would be
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?
> 
I agree.

> 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 
this respect.

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 !

Geert