On 9/3/2010 10:52 AM, Geert Janssens wrote:
Tom,
I am reading through your draft content. Nice work so far, thanks.
Below are some suggestions that could help you improve on it. Feel free to
agree or disagree with any of them though :)
* Some words are split across lines, like amoratiza<newline>tion in the first
listitem of your first ordered list. I'm not really sure that is a good idea.
As far as I know xml, it will replace any sequence of whitspaces with exactly
one space, so this would end up in the documentation as amortiaza tion. As far
as I know you can't assume the final document to split lines in the same
places are your source. So as I see it, these split words are best
concatenated again.
I agree. I have concatenated all (I hope!) the splits in the current
version I am working on.
* In this paragraph:
<para>Recording the expenditures on the trip would be much the same.
That is, if you paid by cash you would debit (increase) the reimburse
able expense account for the money paid in cash and credit (decrease)
the Bank account for the payment made. If the traveler paid by credit
card, the debit side would be the same as just described, but the
credit (here, an increase) would be to the account for the credit card
company.</para>
=> Shouldn't Bank account in your example really be "Cash in Wallet account"
or "Cash Asset account" or simply "Cash account" ? I think it's confusing at
least if not incorrect to refer to a Bank account for a cash payment.
Well, what you point out is that I am writing for someone who does not
have such an account on their books. Since GC has modeled that
possibility, I should be consistent and rework the above description to
recognize that possibility. Good of you to catch that.
I have been an accountant for more than 30 years and most of my
experience has reflected the position that once cash is withdrawn from
the bank, it is spent on the purpose for which it was withdrawn. If the
booking of the withdrawal at the time of withdrawal later changes, a
journal entry usually is made to reflect the change.
But your point is well taken also in that what you point out is that GC
documentation, at least for businesses, seems to be missing a treatment
description for handling petty cash: what it is, how it works. I guess
that would be another patch at some point.
* There's another split word in that paragraph by the way:
"reimbourse<newline>able"
Thanks for catching that. I will look for it in my current version.
* In the Reimbursable Expense topic you describe several debit actions as
"increase" and credit actions as "decrease". In the Travel Expense topic
however, you call both the credit and debit actions "increase".
I will check that out to fix any error and clarify what I mean.
* My spelling checker seems to prefer "reimbursable" instead of
"reimburseable", but I'm not a native English speaker so I can't tell you for
sure which one should be correct.
I will check what my spell checker specifies. I am using US English and
that may be the difference or it may be my spelling error.
* You have set some titles in all caps (CURRENT ASSETS, SHORT OR LONG-TERM
ASSETS and LONG-TERM (FIXED) ASSETS). I'd propose not to do that. It's up to
the stylesheet in the end to decide how to display the information and how
titles and subtitles should be visually make distinct.
Good point. When writing in a text editor, I don't see the stylesheet
effects. Thanks for pointing that out.
* You sometimes refer to other sections in either your document or elsewhere
in the guide (like you refer to depreciation elsewhere in the guide, or refer
to your own main topics from higher up in the document). It can be interesting
to make such references actual links users can click on. You can find examples
of this throughout the guide (for example in chapter 2.2 Data Entry Concepts).
Good point. How to do that?
* In paragraph:
<para><guilabel>Leasehold Improvements</guilabel> Where a business does
not own the building where it ...
How about: When a business does not own the building where it...
Yes, too much colloquial expression. It takes another pair of eyes to
see that quickly. Thanks.
* In that same paragraph you suddenly switch from debit (increase) to increase
(debit).
To be investigated. (TBI).
* The debit/credit vs increase/decrease wording has always confused me.
Perhaps it it worth to spend a thourough section on this on its own early on
in the guide and then use debit/credit only throughout the rest of the guide.
Then you won't have to repeat the clarification between parentheses again and
again.
I agree with you.
I have been doing that because earlier versions of the documentation
have been doing that. What the GC docs do not have is a separate
section dealing with the "normal balance" concept. If that were
introduced than much of the present documents (not just my patch) could
be simplified. What I believe should happen is that chapter 2 needs to
be rewritten and deal with basic accounting concepts not treated there.
That treatment would include clear examples and graphics in addition to
what is there now. Once that is in place, then Chapter 3 could more
easily be the place where the main sections of the chart of accounts
(CoA) could be presented in a context of the standard reports that
accounting generates: Balance Sheet, Income Statement, Statement of Cash
Flows. Once the standard reports are presented, all other possible
reports can be related to these 3 as specialized analyses of segments of
the CoA.
There is a logical development and flow in accounting and it can grow as
the needs of the person keeping records increase. I have not started
from the most logical position. Instead I started being willing to work
on documentation on a user question and the answer provided, which
really is beginning somewhere in the middle rather than using beginning
concepts.
* On a more general note: the guide is organized in big topics (Accounts,
Transactions,...) and each of these big topics is then detailed in basically
three sub topics
1. Concepts (sometimes also called Basic Concepts)
2. Some sections how it all works
3. How to set it up and work with it inside GnuCash ("Putting it all
together")
Your new documentation seems to mix these three more or less together. I'm not
saying that's wrong or not proper. I'm just pointing it out. You can feel for
yourself if it would make sense and if you're willing to reorganize the
information in the same overall structure or not.
You make a point here. If the history of GC communication to the user
has been oriented primarily to the practical as opposed to the
conceptual, then people without accounting training could miss the
significance of any description they don't have an immediate use for.
Perhaps the overall structure of the Guide should be a blend of
practical and conceptual: Introduction and Concepts [short history of
how accounting evolved, basic concepts, CoA, fundamental reports ],
Mechanics of Basic Parts [your big parts and present documentation
approach], Business Needs [some of my patch in process, specialized
needs, such as the tax reporting issues that shows up repeatedly in the
lists.]
If that makes sense to the developers, then I have no problem with
regrouping along those lines.
* And lastly, while I find your added information very valuable, I'm not sure
chapter 3 is the right place to add it. Your new sections detail some advanced
uses of the asset type of accounts, mostly used in a business context. I don't
think people reading the guide as a first introduction to accounting and
GnuCash would be able to grasp these business concepts. In my opinion, your
information is worth to be a chapter on its own. I would put it right before
the Depreciation chapter and call it "Assets Accounts Revisited" or "Advanced
Use Of Asset Accounts" or something like that.
See my reply above. I generally agree with your observations. You
comment here could be applied to much more than what I have proposed in
my patch. If my proposed structure could be agreed on, then the bulk of
the current documentation would be in the Mechanics of Basic Parts segment.
We would need a plan to stage the implementation I propose. I visualize
using a lot more links like you suggested above so that a Guide user
could link back and forth between concepts and practical use.
What do you think of these suggestions ?
Great ideas. Tell me what you think of my replies. If accepted, it
means I defer my Chapter 3 implementation and rework in a different
manner. Other than implementing error fixes I will defer until the
notion I proposed is discussed.
Tom
Geert
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
