Draft content now in new location

[Tom Bullock]

  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