Re: [GNC] Documentation changes needed

[Frank H. Ellenberger]

Hi Phil,

before I start: it seems the mail server rejected your mail because of
the for it unknown attachment. Perhaps Derek will comment on that later.

Thunderbird did not display your attachment. I had to trick it to
display it in LibreOffice.

David is right, just register your wiki account and start improving the
page. In case of doubt we can revert it. ;-)

As a "technician" I usually do not touch the user written sections 1-4
of the page.

Perhaps we should for now add a link to
https://github.com/Gnucash/gnucash-docs/blob/maint/README
at the beginning. Some points may still be better explained there.

More inline …

Am 11.05.22 um 17:30 schrieb Phillip Duff:
> HI,
> 
> Looks like I might need some help here as well as offering a rewrite for the 
> ‘How to change documentation in GNUCash, which I find difficult, confusing 
> and overly technical when the audience is documenters who may well not be 
> developers.
> 
> It has taken me a whole afternoon to unravel what to do and I have rewritten 
> much of it to completely simplify it and convert it into ’These are the steps 
> you need to take;, type documentation. It is attached. If someone can look at 
> it (it isn’t complete, because as below, I am stuck) and advise me if this is 
> what they consider to be an improvement (note I have deliberately left out 
> some stuff to keep it simple and instructive rather than explanatory).
> 
> Some examples + where I am currently stuck.
> 
> OK, Install Git, no problem.  
> 
> (Needs to have added here for Mac users that if you install XTools, you 
> already have both Git and make (which ic buried further down, too late). We 
> should simply recommend that Xtools is installed, whether it is 4Gb is 
> irrelevant in today’s world generally, and we should move away from command 
> line wherever possible for documenters.
> 
> Clone it, no problem.  (Can be easily done using Tools, so I have added it).
> Create the directory structures, no problem (This is then repeated on the 
> ‘Initialising build environment page, so eliminate the repeat).
> 
> Now it gets interesting and very confusing. The page on make is pretty 
> confusing.

We should reorder it from bottom-up to top-down.

> You need CMake to create the directory structures inside build, but there is 
> no mention of that this needs to be downloaded.

Right, should be mentioned before.

> After this we are now positioned to change the documentation , as far as I 
> can see, so I would continue with the documenting of this with a clear set of 
> the instructions needed as documenters only want to know what in Git they 
> need without wading through the Git pages to work it out.

The wiki page Git is terrible. Better link "An Introduction to Git",
which did not exist, when this page was created.

> For the Mac at least, CMake has a user interface, but for some reason the 
> author wants to bring everything back to command line level, so the Make 
> interface should be referenced. Not sure about Linux, so we can leave the 
> command line in for that.

But to reduce redundancy I would suggest to create a separate page for
XCode specifics. As I am no Mac user, I don't know its content. Perhaps
there are already a few similar pages in
https://wiki.gnucash.org/wiki/Category:IDE.

Later Mac users can link it from other occurrences
https://wiki.gnucash.org/wiki/index.php?search=XCode&title=Special%3ASearch&go=Seite


Linux distributions also often have a meta package "[C/C++] Developement
Tools" which should today include Git, Cmake, …

It is often faster to copy the command frome the wiki onto your command
line than describing In IDE x click here and there, but in y use foo and
bar instead. And not everybody knows every environment.

> Except that when I run Cmake pointing to the src and build directories and 
> enabling Mobi, I get errors.
> 
> Can’t find fop, you will be unable to generate pdf files.

Right, they use the same fo interim format like pdf.

> CMake Error in guide/C/CMakeLists.txt:
> The custom command generating
> 
> /Users/philduff/Documents/gnucash-build/share/gnome/help/gnucash-guide/C/fdl-appendix.xml
> 
> is attached to multiple targets:
> 
> C-gnucash-guide-check
> C-gnucash-guide-ghelp
> C-gnucash-guide-html
> C-gnucash-guide-epub
> 
> but none of these is a common dependency of the other(s). This is not
> allowed by the Xcode "new build system”.
> 
> Note that I set the environment to Xtools since it is installed and this 
> seemed like a reasonable assumption.
> Any help ??

AFAIK nobody has tested the Xcode "new build system”. Perhaps John
knows, if it is easily adapted.

> Cheers Phil

Ceers
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 remem

Re: [GNC] Documentation changes needed

[john]

> On May 11, 2022, at 8:30 AM, Phillip Duff  wrote:
> 
> For the Mac at least, CMake has a user interface, but for some reason the 
> author wants to bring everything back to command line level, so the Make 
> interface should be referenced. Not sure about Linux, so we can leave the 
> command line in for that.
> 
> Except that when I run Cmake pointing to the src and build directories and 
> enabling Mobi, I get errors.
> 
> Can’t find fop, you will be unable to generate pdf files.
> 
> CMake Error in guide/C/CMakeLists.txt:
> The custom command generating
> 
> /Users/philduff/Documents/gnucash-build/share/gnome/help/gnucash-guide/C/fdl-appendix.xml
> 
> is attached to multiple targets:
> 
> C-gnucash-guide-check
> C-gnucash-guide-ghelp
> C-gnucash-guide-html
> C-gnucash-guide-epub
> 
> but none of these is a common dependency of the other(s). This is not
> allowed by the Xcode "new build system”.
> 
> Note that I set the environment to Xtools since it is installed and this 
> seemed like a reasonable assumption.
> Any help ??


I'm not familiar with the Cmake GUI interface, but it doesn't look from what I 
find on the web that its able to run its build function from the GUI. The 
CMakeLists aren't set up in a way that's friendly for IDEs so you really are 
best off using the command line. After generating the build system with cmake 
you can use `cmake --build . --target html` but it's less typing to use `make 
html` or better (see next item) `ninja html`.

I suggest that you also install ninja (https://ninja-build.org/ 
), it's much faster than make. Just tell cmake `-G 
Ninja` or select Ninja in the cmak-gui to get ninja build files instead of 
Makefiles. There's a binary available on the website or you can install it with 
either package manager.

It's not necessary for documenters to build PDF, ePub, or MOBI documentation so 
don't worry about FOP.

Regards,
John Ralls



___
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.

Re: [GNC] Documentation changes needed

[john]

> On May 11, 2022, at 8:30 AM, Phillip Duff  wrote:
> 
> (Needs to have added here for Mac users that if you install XTools, you 
> already have both Git and make (which ic buried further down, too late). We 
> should simply recommend that Xtools is installed, whether it is 4Gb is 
> irrelevant in today’s world generally, and we should move away from command 
> line wherever possible for documenters.

I think you mean Xcode that is indeed enormous. There's a smaller alternative 
for command line work called "the command line developer tools". You can 
install that directly with `Xcode-select --install` but since MacOS X 10.11 (El 
Capitan) or so there are stubs for the included commands that pop up a dialog 
box asking if you want to install them, so just type `git` at a terminal prompt 
and click OK.

Regards,
John Ralls

___
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.

Re: [GNC] Documentation changes needed

[Phillip Duff]

HI,

Looks like I might need some help here as well as offering a rewrite for the 
‘How to change documentation in GNUCash, which I find difficult, confusing and 
overly technical when the audience is documenters who may well not be 
developers.

It has taken me a whole afternoon to unravel what to do and I have rewritten 
much of it to completely simplify it and convert it into ’These are the steps 
you need to take;, type documentation. It is attached. If someone can look at 
it (it isn’t complete, because as below, I am stuck) and advise me if this is 
what they consider to be an improvement (note I have deliberately left out some 
stuff to keep it simple and instructive rather than explanatory).

Some examples + where I am currently stuck.

OK, Install Git, no problem.  

(Needs to have added here for Mac users that if you install XTools, you already 
have both Git and make (which ic buried further down, too late). We should 
simply recommend that Xtools is installed, whether it is 4Gb is irrelevant in 
today’s world generally, and we should move away from command line wherever 
possible for documenters.

Clone it, no problem.  (Can be easily done using Tools, so I have added it).
Create the directory structures, no problem (This is then repeated on the 
‘Initialising build environment page, so eliminate the repeat).

Now it gets interesting and very confusing. The page on make is pretty 
confusing.

You need CMake to create the directory structures inside build, but there is no 
mention of that this needs to be downloaded.

After this we are now positioned to change the documentation , as far as I can 
see, so I would continue with the documenting of this with a clear set of the 
instructions needed as documenters only want to know what in Git they need 
without wading through the Git pages to work it out.


For the Mac at least, CMake has a user interface, but for some reason the 
author wants to bring everything back to command line level, so the Make 
interface should be referenced. Not sure about Linux, so we can leave the 
command line in for that.

Except that when I run Cmake pointing to the src and build directories and 
enabling Mobi, I get errors.

Can’t find fop, you will be unable to generate pdf files.

CMake Error in guide/C/CMakeLists.txt:
The custom command generating

/Users/philduff/Documents/gnucash-build/share/gnome/help/gnucash-guide/C/fdl-appendix.xml

is attached to multiple targets:

C-gnucash-guide-check
C-gnucash-guide-ghelp
C-gnucash-guide-html
C-gnucash-guide-epub

but none of these is a common dependency of the other(s). This is not
allowed by the Xcode "new build system”.

Note that I set the environment to Xtools since it is installed and this seemed 
like a reasonable assumption.
Any help ??

Cheers Phil

 






> On 30 Apr 2022, at 17:21, David T.  wrote:
> 
> 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 w

Re: [GNC] Documentation changes needed

[David T. via gnucash-user]

Phillip, 

Your attachment uses a proprietary format that many might find difficult to 
open. I know I do. Perhaps you could create a pdf?

If you think you can improve the wiki page, you should just go for it. 

As for the complexity of the tools and the process, I can only agree. 

David

On May 11, 2022 11:30:47 AM EDT, Phillip Duff  wrote:
>HI,
>
>Looks like I might need some help here as well as offering a rewrite for the 
>‘How to change documentation in GNUCash, which I find difficult, confusing and 
>overly technical when the audience is documenters who may well not be 
>developers.
>
>It has taken me a whole afternoon to unravel what to do and I have rewritten 
>much of it to completely simplify it and convert it into ’These are the steps 
>you need to take;, type documentation. It is attached. If someone can look at 
>it (it isn’t complete, because as below, I am stuck) and advise me if this is 
>what they consider to be an improvement (note I have deliberately left out 
>some stuff to keep it simple and instructive rather than explanatory).
>
>Some examples + where I am currently stuck.
>
>OK, Install Git, no problem.  
>
>(Needs to have added here for Mac users that if you install XTools, you 
>already have both Git and make (which ic buried further down, too late). We 
>should simply recommend that Xtools is installed, whether it is 4Gb is 
>irrelevant in today’s world generally, and we should move away from command 
>line wherever possible for documenters.
>
>Clone it, no problem.  (Can be easily done using Tools, so I have added it).
>Create the directory structures, no problem (This is then repeated on the 
>‘Initialising build environment page, so eliminate the repeat).
>
>Now it gets interesting and very confusing. The page on make is pretty 
>confusing.
>
>You need CMake to create the directory structures inside build, but there is 
>no mention of that this needs to be downloaded.
>
>After this we are now positioned to change the documentation , as far as I can 
>see, so I would continue with the documenting of this with a clear set of the 
>instructions needed as documenters only want to know what in Git they need 
>without wading through the Git pages to work it out.
>
>
>For the Mac at least, CMake has a user interface, but for some reason the 
>author wants to bring everything back to command line level, so the Make 
>interface should be referenced. Not sure about Linux, so we can leave the 
>command line in for that.
>
>Except that when I run Cmake pointing to the src and build directories and 
>enabling Mobi, I get errors.
>
>Can’t find fop, you will be unable to generate pdf files.
>
>CMake Error in guide/C/CMakeLists.txt:
>The custom command generating
>
>/Users/philduff/Documents/gnucash-build/share/gnome/help/gnucash-guide/C/fdl-appendix.xml
>
>is attached to multiple targets:
>
>C-gnucash-guide-check
>C-gnucash-guide-ghelp
>C-gnucash-guide-html
>C-gnucash-guide-epub
>
>but none of these is a common dependency of the other(s). This is not
>allowed by the Xcode "new build system”.
>
>Note that I set the environment to Xtools since it is installed and this 
>seemed like a reasonable assumption.
>Any help ??
>
>Cheers Phil
>
> 
>
>
>
>
>
>
>> On 30 Apr 2022, at 17:21, David T.  wrote:
>> 
>> 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 informati

Re: [GNC] Documentation changes needed

[David T. via gnucash-user]

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  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

Re: [GNC] Documentation changes needed

[Frank H. Ellenberger]

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  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 thing

Re: [GNC] Documentation changes needed

[David T. via gnucash-user]

Phillip, 

Good to hear that someone is interested in working on the documentation! 

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

Let me know if you have questions. 

Best, 
David T.

On April 22, 2022 3:51:37 AM EDT, Phillip Duff  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.
>
>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.
>
>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.
>
>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

[GNC] Documentation changes needed

[Phillip Duff]

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.

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.

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.

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 
inf