Difference between revisions of "Concept Guide"

From GnuCash
Jump to: navigation, search
(Areas that need work)
m (Update Categories)
 
(22 intermediate revisions by 8 users not shown)
Line 1: Line 1:
= Road towards 2.0 =
+
[[Category:Documentation Development]]
 +
This page is not a Concept Guide itself;  this is a Wiki page about development of the ''GnuCash Tutorial and Concept Guide'', which is available at [http://www.gnucash.org/viewdoc.phtml?doc=guide http://www.gnucash.org/viewdoc.phtml?doc=guide].
  
This page is just a temporary page to keep track of the progress of the concept guide, as well as what needs to be done with it.
+
== Introduction ==
Please feel free to add to it, with various thoughts and comments.
+
The ''GnuCash Tutorial and Concept Guide'' (the ''Guide'') is intended to be a document where the main concepts behind GnuCash are explained and where every feature of the software is illustrated with step-by-step examples. To put it another way, think of the ''Guide'' as the official GnuCash ‘definitive guide’ technical manual in the style of [http://search.oreilly.com/?i=1&q=the+definitive+guide&t1=Books&u1=q&u2=t1&facet=ContentType&act=fc_contenttype_Books O’Reilly’s guides]. It should provide clear guidance to GnuCash users on how to do their personal or small business accounting.
Especially in things that needs to be clearer, or items that are missing etc.
 
  
== Check out document ==
+
Detailed descriptions of the GUI, commands, options, toolbar buttons etc. must go into the ''GnuCash Help Manual'' (the ''Manual'') instead.  It would be best to have the ''Guide'' illustrate how to perform an accounting task, with links to the corresponding detailed descriptions in the ''Manual''.
  svn checkout <nowiki>http://svn.gnucash.org/repo/gnucash-docs/trunk</nowiki> gnucash-docs
 
  
== Review ==
+
This page is just a temporary page for volunteers developing the ''Guide''. It may include broad plans and/or detailed worklists of writing tasks to be done.  Please feel free to add to it, with various thoughts and comments.  Especially in things that needs to be clearer, or items that are missing etc.  In order for numerous volunteers to coordinate their efforts smoothly, this Wiki page should be developed gradually with emergence of consensus on how it should appear.  Please use the "Discussion" tab to make proposals and otherwise discuss the development of this page.
Please read through the [http://cvs.gnucash.org/docs/guide/ svn version of Concept Guide] (or from SVN as above) and indicate on this wiki which areas need to be reworked, modified, deleted, added, or left unchanged.
 
  
We can use this wiki page to discuss what should be in the guide, and which examples.
+
For detailed instructions on how the documentation update process works, see [http://wiki.gnucash.org/wiki/Documentation_Update_Instructions Documentation Update Instructions].
Later on, we can use the gnucash-devel list to send out the raw text for quick reviews
 
 
 
== Updating the concept guide ==
 
Please co-ordinate and inform of your intentions on gnucash-devel as well as on this wiki.
 
  
# Have a read of the Gnome documentation documents.
+
== Review of the existing ''Tutorial and Concepts Guide'' in May 2017==
##http://library.gnome.org/devel/gdp-handbook/stable/
+
A new review of the existing ''Guide'' is needed now, in May of 2017.
##http://library.gnome.org/devel/gdp-style-guide/stable/
 
# Ensure you have the latest copy from subversion
 
#* svn update
 
# Update the Wiki, Move the chapter to Ongoing work
 
# Add revision and your name to the authors block. See sample below
 
<pre>
 
<!--
 
      (Do not remove this comment block.)
 
  Version: 1.9.x
 
  Last modified: April 16th 2006
 
  Version: 1.8.4
 
  Last modified: April 10th 2004
 
  Maintainers:
 
              Chris Lyttle <chris@wilddev.net>
 
  Author:
 
  Jon Lapham <lapham@extracta.com.br>
 
  Updated Bengt Thuree <bengt@thuree.com>
 
  Originally written by Carol Champagne.
 
  Translators:
 
              (translators put your name and email here)
 
-->
 
</pre>
 
# Modify the xml file, and check the result with yelp
 
#*  I am using scite as my editor, a plain editor like gedit, but it can "compress" the various tag pairs. Or use emacs with docbook extension
 
#* yelp gnucash-guide.xml
 
#* The XMLmind XML editor for Windows is free for personal use, and works fine. It also validates as well as clean up the XML code.
 
#** www.xmlmind.com/xmleditor
 
# For screenshots
 
#* Ensure you are using the default Gnome theme (ClearLooks)
 
#* Make the screenshots as small as possible
 
#* Use GIMP to take the screen shots (Aquire with delay)
 
#* Use Gimp --> Image --> Scale to ensure the width is max 510 pixels.
 
#* Save screenshot as a png file.
 
#* Ensure you are using the standard C locale. LANG=C ./gnucash
 
# Spell Check the document.
 
# Clean up docbook tags
 
#* xmllint --valid --noout gnucash-guide.xml
 
#* yelp gnucash-guide.xml
 
#* xmlto -o /tmp txt gnucash-guide.xml
 
# Prepare a text diff (if new file, or major formatting changes)
 
<pre>
 
## SVN gnucash-guide.xml
 
xmlto -o /tmp txt gnucash-guide.xml
 
rename /tmp/gnucash-guide.txt to /tmp/gnucash-guide.svn.txt
 
  
## Modified gnucash-guide.xml
+
== Review (outdated) ==
xmlto -o /tmp txt gnucash-guide.xml
+
Please read through the ''Tutorial and Concepts Guide'' in the '''Nightly Documentation Builds''' section of the [http://www.gnucash.org/docs.phtml documentation page] and indicate on this wiki any areas that you think need to be reworked, modified, deleted, added, or left unchanged.
rename /tmp/gnucash-guide.xml to /tmp/gnucash-guide.new.xml
 
  
diff -u /tmp/gnucash-guide.svn.txt /tmp/gnucash-guide.new.txt
+
We can use this wiki page to discuss what should be in the guide, and which examples.
</pre>
+
Later on, we can use the gnucash-devel list to send out the raw text for quick reviews
#Prepare an subversion diff
 
<pre>svn diff > MyChanges.diff</pre>
 
# Double check that the svn version has not been modified.
 
# Submit your contribution to the GnuCash team
 
#* Send the text based diff file to the -devel list (if major formatting changes or new file)
 
#* Send the subversion diff file to -devel (if minor changes)
 
#* Send the xml (if new file or if you did major formatting changes) to -devel
 
#* Send the screenshots directly to Chris, and other interested parties after some time passed to let comments have a chance to filter back.
 
  
 
= Areas that need work =
 
= Areas that need work =
Line 83: Line 24:
  
 
In most part of the doumentation the "Forward" button in assistants is erroneously referred to as "Next".
 
In most part of the doumentation the "Forward" button in assistants is erroneously referred to as "Next".
 +
 +
The "druid" word is deprecated. So if you encounter it, substitute it with "assistant"
  
 
The following items have missing text in the existing guide, or just need more work
 
The following items have missing text in the existing guide, or just need more work
Line 88: Line 31:
 
* Search
 
* Search
 
* Bugs
 
* Bugs
** [[http://bugzilla.gnome.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=GnuCash&component=Documentation&long_desc_type=substring&long_desc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=NEEDINFO&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailqa_contact2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=|Document bugs in bugzilla]]
+
** [[{{BugURL}}/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=GnuCash&component=Documentation&long_desc_type=substring&long_desc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=NEEDINFO&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailqa_contact2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=|Document bugs in bugzilla]]
** http://bugzilla.gnome.org/show_bug.cgi?id=105932
+
** {{BugURL}}/show_bug.cgi?id=105932
** http://bugzilla.gnome.org/show_bug.cgi?id=106242
+
** {{BugURL}}/show_bug.cgi?id=106242
** http://bugzilla.gnome.org/show_bug.cgi?id=99477
+
** {{BugURL}}/show_bug.cgi?id=99477
** http://bugzilla.gnome.org/show_bug.cgi?id=98292
+
** {{BugURL}}/show_bug.cgi?id=98292
** http://bugzilla.gnome.org/show_bug.cgi?id=303164
+
** {{BugURL}}/show_bug.cgi?id=303164
 
* Scripts
 
* Scripts
 
** gnc-fq-check
 
** gnc-fq-check
Line 128: Line 71:
 
= Ready for review =
 
= Ready for review =
 
The following chapters have been modified and are ready for review
 
The following chapters have been modified and are ready for review
* 1. Overview
+
 
 
* 2. Basics (ready for review on dev-list [https://lists.gnucash.org/pipermail/gnucash-devel/2010-October/029755.html here])
 
* 2. Basics (ready for review on dev-list [https://lists.gnucash.org/pipermail/gnucash-devel/2010-October/029755.html here])
* 3. Accounts
 
* 4. Transactions
 
* 5. Checkbook
 
* 6. Credit Cards
 
* 7. Loans
 
* 8. Investments
 
* 9. Capital Gains 
 
* 10. Multiple Currencies
 
* 11. Depreciation
 
* 12. Accounts Receivable
 
* 13. Accounts Payable           
 
* 14. Payroll
 
  
 
= Ongoing work =
 
= Ongoing work =
Line 158: Line 89:
  
 
Once integrated into the guide, the content here will be removed and a stub left indicating the date of integration into the official Guide.
 
Once integrated into the guide, the content here will be removed and a stub left indicating the date of integration into the official Guide.
 +
 +
=== Chapter: The Basics ===
 +
 +
Updating the screenshots referred in the "ch_basics.xml" file
  
 
=== Chapter: Other Assets ===
 
=== Chapter: Other Assets ===
Line 226: Line 161:
 
** Migrating from Quicken/Money
 
** Migrating from Quicken/Money
 
*** I think we need to come with more details on this area? (expand on 2.7. Importing QIF Files, and Appendix A)
 
*** I think we need to come with more details on this area? (expand on 2.7. Importing QIF Files, and Appendix A)
** Ensure that the numbers in the QIF file do not contain " " (http://bugzilla.gnome.org/show_bug.cgi?id=121443)
+
** Ensure that the numbers in the QIF file do not contain " " ({{BugURL}}/show_bug.cgi?id=121443)
 
** Sample of QIF file, and links to more samples
 
** Sample of QIF file, and links to more samples
 +
 +
= Updating the concept guide =
 +
Please co-ordinate and inform of your intentions on gnucash-devel as well as on this wiki.
 +
 +
# Have a read of the Gnome documentation documents.
 +
##<s>http://library.gnome.org/devel/gdp-handbook/stable/</s> Since Gnome3 this link is broken. Linux users can install <tt>gnome-devel-docs</tt> and in <code>yelp</code> use <tt>Menu->All Documents</tt> to view them.
 +
##http://library.gnome.org/devel/gdp-style-guide/stable/
 +
# Ensure you have the latest copy from git
 +
  git pull --rebase
 +
# Update the Wiki, Move the chapter to Ongoing work
 +
# Add revision and your name to the authors block. See sample below
 +
<pre>
 +
<!--
 +
      (Do not remove this comment block.)
 +
  Version: 1.9.x
 +
  Last modified: April 16th 2006
 +
  Version: 1.8.4
 +
  Last modified: April 10th 2004
 +
  Maintainers:
 +
              Chris Lyttle <chris@wilddev.net>
 +
  Author:
 +
  Jon Lapham <lapham@extracta.com.br>
 +
  Updated Bengt Thuree <bengt@thuree.com>
 +
  Originally written by Carol Champagne.
 +
  Translators:
 +
              (translators put your name and email here)
 +
-->
 +
</pre>
 +
# Modify the xml file, and check the result with yelp
 +
#*  I am using scite as my editor, a plain editor like gedit, but it can "compress" the various tag pairs. Or use emacs with docbook extension
 +
#* yelp gnucash-guide.xml
 +
#* The XMLmind XML editor for Windows is free for personal use, and works fine. It also validates as well as clean up the XML code.
 +
#** www.xmlmind.com/xmleditor
 +
# For screenshots
 +
#* Ensure you are using the default Gnome theme (ClearLooks)
 +
#* Make the screenshots as small as possible
 +
#* Use GIMP to take the screen shots (Aquire with delay)
 +
#* Use Gimp --> Image --> Scale to ensure the width is max 510 pixels.
 +
#* Save screenshot as a png file.
 +
#* Ensure you are using the standard C locale. LANG=C ./gnucash
 +
# Spell Check the document.
 +
# Clean up docbook tags
 +
#* xmllint --valid --noout gnucash-guide.xml
 +
#* yelp gnucash-guide.xml
 +
#* xmlto -o /tmp txt gnucash-guide.xml
 +
# Commit your changes and prepare a patch:
 +
#* If you've created a new file, add it to the index:<br><code>git add path/to/new/file</code>
 +
#* Commit<br><code>git commit</code>
 +
#* Write a nice commit message explaining your changes.
 +
#* Unless you have commit privileges at the master repository, make a patch:<br><code>git format-patch master</code>
 +
#* Patches may be emailed to gnucash-devel@gnucash.org or attached to bugs in [[Bugzilla]]. The latter is preferred, as patches on the mailing list may be missed or forgotten.

Latest revision as of 12:05, 31 December 2021

This page is not a Concept Guide itself; this is a Wiki page about development of the GnuCash Tutorial and Concept Guide, which is available at http://www.gnucash.org/viewdoc.phtml?doc=guide.

Introduction

The GnuCash Tutorial and Concept Guide (the Guide) is intended to be a document where the main concepts behind GnuCash are explained and where every feature of the software is illustrated with step-by-step examples. To put it another way, think of the Guide as the official GnuCash ‘definitive guide’ technical manual in the style of O’Reilly’s guides. It should provide clear guidance to GnuCash users on how to do their personal or small business accounting.

Detailed descriptions of the GUI, commands, options, toolbar buttons etc. must go into the GnuCash Help Manual (the Manual) instead. It would be best to have the Guide illustrate how to perform an accounting task, with links to the corresponding detailed descriptions in the Manual.

This page is just a temporary page for volunteers developing the Guide. It may include broad plans and/or detailed worklists of writing tasks to be done. Please feel free to add to it, with various thoughts and comments. Especially in things that needs to be clearer, or items that are missing etc. In order for numerous volunteers to coordinate their efforts smoothly, this Wiki page should be developed gradually with emergence of consensus on how it should appear. Please use the "Discussion" tab to make proposals and otherwise discuss the development of this page.

For detailed instructions on how the documentation update process works, see Documentation Update Instructions.

Review of the existing Tutorial and Concepts Guide in May 2017

A new review of the existing Guide is needed now, in May of 2017.

Review (outdated)

Please read through the Tutorial and Concepts Guide in the Nightly Documentation Builds section of the documentation page and indicate on this wiki any areas that you think need to be reworked, modified, deleted, added, or left unchanged.

We can use this wiki page to discuss what should be in the guide, and which examples. Later on, we can use the gnucash-devel list to send out the raw text for quick reviews

Areas that need work

To better follow the GDP rules, it's adviced to substitute the construction for menu item with the -&gt symbol by using a markup like this: <menuchoice><guimenu>File</guimenu><guisubmenu>Import...</guisubmenu><guimenuitem>Import QIF</guimenuitem></menuchoice>.

In most part of the doumentation the "Forward" button in assistants is erroneously referred to as "Next".

The "druid" word is deprecated. So if you encounter it, substitute it with "assistant"

The following items have missing text in the existing guide, or just need more work

Ready for release

The following chapters have been review/modified and are ready for release

Ready for review

The following chapters have been modified and are ready for review

  • 2. Basics (ready for review on dev-list here)

Ongoing work

GnuCash Tutorial and Concepts Guide

This document title duplicates the title of the official GnuCash software documentation that currently exists [1] as part of the information available to current and new users of the GnuCash double-entry accounting freeware product.

However, the official document as it exists currently covers features only through version 2.2.[2] The current stable version is 2.2.9 [2], and that is soon to be updated and replaced by the pending version 2.4.

Because the introduction of new features has exceeded the pace at which the documentation has been able to keep current, this page is intended to be a repository for new feature descriptions and instructions how-to-use those features. The intent is to provide easy access for gnucash users to review the proposed documentation with the end result of stamping it approved or identifying shortcomings that need update and correction.

Once that process has resulted in the content reaching a stable point, that portion of the new documentation will be moved into the official GnuCash Tutorial and Concepts Guide.

Since the official Guide is organized by chapters, all entries on this page will reference the place in the current official documentation that is intended as its ultimate destination.

Once integrated into the guide, the content here will be removed and a stub left indicating the date of integration into the official Guide.

Chapter: The Basics

Updating the screenshots referred in the "ch_basics.xml" file

Chapter: Other Assets

Content has been added into the official GnuCash repository as of revision 19618.

Remaining work

The chapters below have not been modified/checked since the 1.8 series.

General

  • Add screenshots for the budget chapter

Personal

Business

Appendix

  • A. Migration Guide
  • B. Frequent Asked Questions (we need to update with the valid FQA)

Thoughts and comments

  • Reports -
    • Add a sub chapter in each chapter regarding to Reports valid to current chapter
    • Add a separate chapter with an overview of the current reports
  • Make examples with separate accounts for each stocks/brokearage income/expense, so we can track each stocks costs
  • Ensure the account structure and names follow the default convention (Change "Starting Values" to "Opening Balances" for instance)
  • One datafile per chapter, and the chapter has to explain how to create the datafile with all its entries.
  • If you have multiple bank accounts with one bank the following should be an example?
    • Asset:Bank:CitiBank:Saving
    • Asset:Bank:CitiBank:ATM
  • Multiple currencies
    • the business features are all currently single-currency reference
    • Equity:Opening Balance:USD
    • Equity:Opening Balance:AUD
    • Income:Saving:CitiBank:Interest (where CitiBank is all in USD)
    • Expenses:Bank:CitiBank:Interest (where CitiBank is all in USD)
    • Expenses:Bank:CitiBank:Charges (where CitiBank is all in USD)
    • Income:Saving:Boom:Interest:HKD (boom has one USD and one HKD account)
    • Income:Saving:Boom:Interest:USD (boom has one USD and one HKD account)
  • Investments
    • Verify Capital Gains/Dividens in reports. Details
    • When you create a commodity, you should also directly create the Dividend account
    • How to Add / Remove shares
    • How to move shares between brokerage accounts.
    • How to do imediate re-invest dividend
    • How to buy shares with NON-Default currency
      • Current workaround: Buy the shares from the BANK account, and right click on the stock purchase row and select "Edit Exchange Rate"
Default currency AUD (not HKD)
Commodity Stock_1
Assets:Banks:Boom:HKD
Assets:Brokerage Accounts:Boom:Stock_1
Expenses:Investments:Commission:Boom_HKD
Income:Investments:Dividend:Boom_HKD:Stock_1
Open Assets:Banks:Boom:HKD account
Buy Stocks 
                Assets:Banks:Boom:HKD                                   Withdrawal 10,000
                Expenses:Investments:Commission:Boom_HKD    Deposit 500
                Assets:Brokerage Accounts:Boom:Stock_1      Deposit 9,500
Right click on the last row, and select "Edit Exchange Data"
In the following pop up window, enter the actual number of stocks in the last entry box 
 (not the default entry box)
  • Assets
    • Personal loan to a friend (Assets:Money owed to you:<Friends name>)
    • Depreciation of private assets like Car and other items (house, horse etc)
  • QIF Import
    • Migrating from Quicken/Money
      • I think we need to come with more details on this area? (expand on 2.7. Importing QIF Files, and Appendix A)
    • Ensure that the numbers in the QIF file do not contain " " (https://bugs.gnucash.org/show_bug.cgi?id=121443)
    • Sample of QIF file, and links to more samples

Updating the concept guide

Please co-ordinate and inform of your intentions on gnucash-devel as well as on this wiki.

  1. Have a read of the Gnome documentation documents.
    1. http://library.gnome.org/devel/gdp-handbook/stable/ Since Gnome3 this link is broken. Linux users can install gnome-devel-docs and in yelp use Menu->All Documents to view them.
    2. http://library.gnome.org/devel/gdp-style-guide/stable/
  2. Ensure you have the latest copy from git
 git pull --rebase
  1. Update the Wiki, Move the chapter to Ongoing work
  2. Add revision and your name to the authors block. See sample below
 <!--
      (Do not remove this comment block.)
  Version: 1.9.x
  Last modified: April 16th 2006
  Version: 1.8.4
  Last modified: April 10th 2004
  Maintainers: 
               Chris Lyttle <chris@wilddev.net>
  Author:
  		Jon Lapham <lapham@extracta.com.br>
  	Updated	Bengt Thuree <bengt@thuree.com>
  Originally written by Carol Champagne.
  Translators:
               (translators put your name and email here)
-->
  1. Modify the xml file, and check the result with yelp
    • I am using scite as my editor, a plain editor like gedit, but it can "compress" the various tag pairs. Or use emacs with docbook extension
    • yelp gnucash-guide.xml
    • The XMLmind XML editor for Windows is free for personal use, and works fine. It also validates as well as clean up the XML code.
      • www.xmlmind.com/xmleditor
  2. For screenshots
    • Ensure you are using the default Gnome theme (ClearLooks)
    • Make the screenshots as small as possible
    • Use GIMP to take the screen shots (Aquire with delay)
    • Use Gimp --> Image --> Scale to ensure the width is max 510 pixels.
    • Save screenshot as a png file.
    • Ensure you are using the standard C locale. LANG=C ./gnucash
  3. Spell Check the document.
  4. Clean up docbook tags
    • xmllint --valid --noout gnucash-guide.xml
    • yelp gnucash-guide.xml
    • xmlto -o /tmp txt gnucash-guide.xml
  5. Commit your changes and prepare a patch:
    • If you've created a new file, add it to the index:
      git add path/to/new/file
    • Commit
      git commit
    • Write a nice commit message explaining your changes.
    • Unless you have commit privileges at the master repository, make a patch:
      git format-patch master
    • Patches may be emailed to gnucash-devel@gnucash.org or attached to bugs in Bugzilla. The latter is preferred, as patches on the mailing list may be missed or forgotten.