Frank,
I disagree with your assertion regarding placing transitory information
(such as the current state of the installation process of Finance::Quote
on Macos) into documentation rather than the wiki. There's an
installation page on the wiki for just that reason.
But this is just another example that demonstrates why I gave up trying
to help manage the documentation: the fact that when push comes to
shove, it's Frank's way that holds final sway on how the documentation
turns out. I thank you, Frank, for reminding me of that. I'll drop out
of this discussion now. Good luck, Phillip; I hope it goes well.
David T.
On 4/30/2022 10:16 AM, Frank H. Ellenberger wrote:
Hi together,
Am 23.04.22 um 20:04 schrieb David T. via gnucash-user:
Phillip,
Good to hear that someone is interested in working on the documentation!
Christian Wehling is permanently working on the manual (help) starting
from translating to German and backporting improvements to the english
version.
Also TANIGUCHI Yasuaki has still pending PRs mostly on the Guide,
Chris Good contributed updates,
Pedro Albuquerque updated the pt translation …
The main bottleneck: I have currently not enough time to review and
merge the pending PRs in time:
https://github.com/Gnucash/gnucash-docs/pulls
So I will only add a few notes here.
Gnucash uses Bugzilla (bugs.gnucash.org) to suggest enhancements and fix bugs,
and the documentation has its own section there. You will find that there are
numerous documentation bugs and enhancements outstanding there.
There is also a good bit of information on the wiki on how changes to the
documentation are created, edited, submitted, and approved. See, for example,
https://wiki.gnucash.org/wiki/Documentation_Improvement. Any rewrites you do
will of necessity follow those guidelines.
I'll note that the Gnucash documentation also includes the Help Manual-- and
that information about Gnucash's use can also reside there. There has been a
longstanding difference of opinion about what information should go into the
Guide versus the Help, and there are areas that duplicate information.
As for the bifurcation between the Tutorial and Concepts within the Guide, I
think that early writers focused on the Tutorial side of things, whereas later
authors (myself included) have focused more on the concepts side. How that all
turns out is certainly open for discussion.
As for specifics, updates from a fresh perspective are welcome. I'll admit I
haven't given the Guide a close read for a while now.
Your comments about Finance::Quote, however, I'd suggest fit better as wiki
material. Getting stock quotes, while certainly a useful proposition in a
financial system, are technically outside of the formal accounting. Also, there
are plenty of ways to get valuations without F::Q. Furthermore, Macos users
constitute only a portion of the Gnucash user base, and OS-specific
instructions like yours have been addressed in the wiki much more effectively.
So, on the whole, I'd put those on the wiki. You might have a look at
https://wiki.gnucash.org/wiki/Online_Quotes
No, we consider the wiki —besides collecting stuff that goes beyond the
scope— more as a temporary storage, where improvements are easier
developed. Setting up F::Q belongs to the manual
https://github.com/Gnucash/gnucash-docs/pull/248/files
Let me know if you have questions.
Best,
David T.
On April 22, 2022 3:51:37 AM EDT, Phillip Duff <phil.du...@gmail.com> wrote:
Hi,
Issue 1:
For whoever is responsible for your documentation.
I spent 40 years in IT companies in a variety of roles and now retired , I will
offer to rewrite and assist in your documentation. In reviewing your
documentation I think there are a number of improvements that I can offer, and
my first experience with your software is positive, but the documentation can
be a bit frustrating, hence my offer. Don’t get me wrong, there is some good
stuff here , but I believe I can help you improve it a lot. I am looking for a
project in my retirement and this is certainly one which would be fun.
Here a couple of examples:
There is a Tutorial and Concepts guide and also a Contents section. Firstly,
split the Tutorial and Concepts Guide into the two pieces as they have
different purposes (or at a minimum change the name to Concepts and Tutorial as
the Concepts ALWAYS come first.
That change could be your first pull request. But catch the full scope
by e.g. at least
grep -inr "Tutorial" manual/C guide/C
but do not rewrite thr history. I am not sure if we can apply the change
also easy on translations.
Tip: We should create an entity to simplify future mainenance.
If we look at this guide currently, we see for example it is pretty well laid
out and explained but it does present some problems. Here is a simple example.
In Chapter 2.3 we have a section that is in the intro section, but then
immediately launches into how to do things. So it describes how to enter new
accounts in detail, and talks about panels etc (which if it is going to, it
should show examples). The problem is this is supposed to be an intro section
and only gives some of the info, not all the info you need if you are actually
going to do this. On the next page we go into all sorts of detail about
storage, yet this is supposed to be an intro section, so I have gone from
detailed description of setting up accounts to tech detail on how to store.
Then in 2.2.2 we have again detailed instructions on doing things. Then in 2.7
we have a tutorial, great, so this tells how to set up accounts for example,
but it does not deal with the fact that Opening balances can also be set up by
editing an account. Then in 2.8 we start the introduction to what accounts are
when we have already told the user how to set them up in 2.3 and then again in
the tutorial 2.7. The intro to accounts should be before any explanation of how
to set them up, and it must only be in one place to ensure that you don’t get
documentation synch issues.
Yes, a clear division in intro, concept, … using more modern docbook
tags like <glosslist> for the definitions in the concept or <task> for
tutorial lessons …
Note: 2.3 is partialy only a repetition of Help ch. 2 and the begin of
ch. 3.1. That needs some compare and moves into the proper part—
technical details -> Help, didactical -> Guide.
So here is an example of the impact and a much bigger issue, which is that
documentation should reflect the recommenced workflow of how to achieve a goal,
not a description of what the system can do. Whilst an attempt has been made to
do this, it isn’t quite right and here is what happens.
Right.
I read this intro and thought , OK, I get it. Then I went to set up my
accounts. Now when you set up accounts you are focused on setting them up, NOT
adding opening balances, which is a different act. So I set them up according
to the documentation , but which 2.2, 2.7 or as I did, I went to Section 5 as
this is the section called Common Usage and there is a section on accounts, BUT
it does not tell the user the critical thing, which is that you can edit an
account and add the opening balance, so therefore, I wasted lots of time trying
to find how to do it. Also section 5 is wrong by not telling this, and
suggesting you can do an opening transaction with a transfer against opening
balances (this actually is not possible at all, as when you try it, the equity
accounts are not shown in the dropdown list, so the documentation is not
correct.
So all in all this very simple thing was really annoying, but only due to the
documentation, not the software.
So I would rewrite this for you as follows.
Move section 2.3 Running GNUcash. You are in the middle of explaining the
basics so don’t dive into how to use the system and dive out again to concepts
in 2.8, as previously described. All the instructions on HOW to do things
should be in the tutorial.
Combine 2.3.2 New Account Hierarchy Setup with 2.7 tutorial and Section 5, and
only cover everything once in in one place. Ensure that ALL the information
regarding Opening Balances is covered.
More critically the tutorial will show that you set up your account hierarchy
first and THEN you load your opening balances (and mention in passing that you
can add the opening balances if you like when setting ups the accounts (but I
have never seen an accountant do that !).
So the above is a simple example. I completely understand how open source works
with multiple contributors but if we cleaned up a lot of this as a good
starting point it would be far easier. (And of course my next example is that
getting Finance::Quote going relies of technical knowledge which a lot of
people may not have and may not need. The instructions can be dramatically
improved.
Note that some of the other later sections looks pretty good, and may not need
this level of change.
I suggest the following.
If you agree I will rewrite the introduction sections to show you an example of
what I believe would be significant improvement, easier to read and find the
information, include workflow in the tutorials and ensure that everything is
only covered once. You can then assess whether you think my efforts are worth
it, as I would be prepared to devote time to getting these manuals much
improved based on my experience.
If you are not interested in this, then please fix the following.
a) There is no reference to being able to edit an account and add the opening
balance after you have create the account hierarchy. This should be in the
documentation, and shown in the tutorial, and de -prioritze adding opening
balances on account creation as this isn’t how the real world works.
b) Either fix the software or the documentation, as you cannot create an
opening balance transaction transferring from the opening balance account in
equity as the equity accounts are not shown in the dropdown for transfers.
c) If you try to create a stock, you may immediately see the message Finance::
Quote is not installed. The process for adding Finance::Quote for Mac does not
detail the actions necessary and assumes technical knowledge. It should never
assume that knowledge.
So the section in Chapter 11 should read something like this for the Mac.
You need to install Finance::Quote as this is the piece of software which gets
stock quotes automatically for GNUCash. This is not part of GNUCash but we use
it as a well known tool for getting these quotes reliably.
There are two steps.
a) Install Finance::Quote
b) Setup a scheduler to regularly go and get the quotes for your stocks.
Installing Finance::Quote
Step 1. You must have a tool called Xcode installed. Go to the App Store and
download it. It will automatically install.
Step 2: Go to GNUCash in your Applications folder. Right click and select ‘Show
Package Contents’ (as we have include a tool to help you set it up). Go to
/Contents/Resources/bin and locate gnc-fq-update.
Step 4. Check that you have administrator rights to install this. Go to the
Apple menu, select System Preferences, select Users and Groups and ensure that
you have admin under your name as a user, or get your administrator to do this.
Step 5. Go to your Applications folder and find Utilities/Terminal
Step 6 Type sudo then a space, and then drag gnc-fq-update from step 3 into the
terminal window. Hit return.
The Finance::Quote utility will now be installed.
I look forward to hearing from you and in the meantime I will assume you would
like some extra help
Sure
and start re-writing Section 2 etc.
Please create small pull request to avoid update anomalies with other
contributors.
Cheers Phil
Cheers
Frank
_______________________________________________
gnucash-user mailing list
gnucash-user@gnucash.org
To update your subscription preferences or to unsubscribe:
https://lists.gnucash.org/mailman/listinfo/gnucash-user
If you are using Nabble or Gmane, please see
https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
-----
Please remember to CC this list on all your replies.
You can do this by using Reply-To-List or Reply-All.
