David,
I also subscribe to your manifesto:
I agree that the Concept guide should be just that. Not how to specifically
do something using Gnucash
1. A minimal set of basic accounting concepts with reference perhaps to more
detailed material.
2. Some discussion how GnuCash implements these:
e.g
a) Account register as the primary interface
b) Transactions and splits
c) Lots and how they apply to trading accounts and FIFO, LIFO etc
The Help can be implemented as a split between tooltips and context
sensitive help. Tooltips are not really appropriate for objects like windows
where you may be hovering in the window sometimes for extended times and
having a tooltip up would drive you mad. I think context sensitive help is
more appropriate for describing the functionality of more complex display
structures like windows. There is no difficulty I think in implementing this
from a docbook or similarly driven HTML document or set of documents. The
facilities for creating and accessing links does exist in docbooks and in
most alternatives. It would also be possible to structure this so it was
readable as a document. I would see it as being limited fairly strongly to
the minimum necessary description function of the window, button, checkbox
etc. One thing not clear to users from a stricly functional approach is
where there may be down stream consequences of a particular choice. i.e why
would I make specific choice where there may be two or more options
available. (I think this is where the use-case/tutorial approach can be of
value e.g. a link to a recipe/tutorial where the option is used.). Using
the info re modularity and embedding of the xml files in a link I pasted
earlier creating context sensitive help should be feasible as well as
providing access to it as a complete document. (I seem to have uncovered a
bug in bringing up the context sensitive help window at least in the Linux
version of 3.2 but that is a separate issue and is fixable)
I also agree with you about splitting off the tutorial type content from the
Concept Guide into a "How to do that using Gnucash" style section. One
reservation I have about using the wiki, although not a strong one, is that
I find navigation around the wiki can be problematical unless it has a set
of next, previous, up and top type links. One can end up somewhere along a
chain with no way of getting back quickly apart from retracing the links
using the browser back key. One other problem with a WIki for a maintenance
point of view is thatt a link to a page can be deleted and the page becomes
an orphan with no way to logically access it. A search negine will sometimes
find orphan pages in a wiki.
It is equally doable in docbooks xml approach as a separte document. It is
possibly a bit easier to maintain and possibly provide links into it. I
think it would only require some fairly minor code changes to add extra
items to the help menu for example.
This link (http://www.sagehill.net/docbookxsl/Db5Tools.html) provides the
mechanism for linking between different docbooks. It would probably a good
idea to mark any docbook links with a do not delete message for example. so
that editors are aware they may break any linked structure,
I am willing to help with the task of reorganizing the above if the decision
is made to go ahead.
David Cousens
-----
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
