Documentation Processing Ideas

Thomas Bullock tbullock at nd.edu
Wed Aug 4 12:32:54 EDT 2010


<<Snip>>
Ideally, of course, every change will be described in the Changelog, and significant changes will be described in NEWS (significant meaning rewrites/additions to reflect changes in the program's operation.) The reality, unfortunately, is that the only reliable documentation is the SVN log. This is equally true on the code side.
(In that ideal world, developers would at least add comments in the appropriate places in the documentation files describing changes to the code that require changes to the documentation. That world doesn't exist.)

If you want to be rigorous, you'll have to go through the SVN log for gnucash trunk and try to figure out which changes alter the interface or behavior in a way than affects the documentation and make a checklist. That's probably much more easily said than done, because most of the checkin messages are brief and a bit cryptic.

The other approach is to try out everything that is documented and make sure that it still works the way the docs say. You may notice menus or buttons that aren't documented already; you can write about the ones that you can figure out and ask about the others.

Whichever you choose (perhaps a combination), perhaps you could start a wiki page showing what you find. Once it's up, perhaps the devs who've added things in the last couple of years can mention their work there to help you find the undocumented bits.

In fact, it would be worthwhile for all of the devs and the experienced users on the user list to actually read the docs (I for one haven't looked at them since 1.8 or so, and the program has changed a lot since then) and contribute to that wiki page things that they know should be added.

The rest of the wiki is of course another good source of tips, tricks, and workarounds that could be added or used to clarify the docs. There's probably a bunch of obsolete stuff there that could be pruned, too, but that's a separate issue except to note that everything needs to be tested out before it gets added to the docs.

Regards,
John Ralls
<</Snip>>

[<<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.

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.

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.

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?

Tom




More information about the gnucash-devel mailing list