Manual and Guide Versions in the documentation

[John Ralls]

On Aug 3, 2010, at 2:23 PM, Tom Bullock wrote:

> <<snip>>
>  
> Message: 8
> Date: Mon, 2 Aug 2010 12:50:20 -0700
> From: John Ralls <jralls at ceridwen.us>
> Subject: Website Links
>  
> Also, the online manual and guide seem to be for 2.0; it should be updated to 2.2.
>  
> Regards,
> John Ralls
>  
> <</snip>>
>  
> John,
>  
> Your comment raises the question:  What is the process/method that documentation version reporting should follow? 
>  
> Looking at the little I have been working on in the Guide, the top-level NEWS module shows a history of version changes ending at version 2.0.1 dated 10/08/2006.   Before that, leading up to that point,  there is a trail of version changes and implementation dates (I infer) with a brief comment about reason for entry.
>  
> Since the documentation seems to be behind installation of new features, is there a way to identify the features added since the last point at which the documentation did match the feature install?   If that can be figured out, then that provides a “to-do” list for documentation updates (I assume).  It also would suggest the order that patches should be added, if documenting in the order of oldest to newest feature first.
>  
> Your thoughts and anyone else’s experience would be much appreciated to define the scope of what is needed.
>  

Tom,

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