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 <phil.du...@gmail.com> 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. <sunfis...@yahoo.com> 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 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.
