Capital Gains FAQ entry

[David T.]

Alen,

I appreciate your message, as well as your effort and attitude.

I have worked over the years to improve the official documentation (that is, the Help Manual and the Guide), and make those documents as accurate, clear, and up to date as possible. Although there is still a lot of work that can be done to improve these documents, they still represent the place where the most amount of editorial and writing effort have been expended by the GnuCash community. Because of this (and because of my own background in technical writing), I tend to prefer information in those documents—if it exists—over information that is put on the wiki. When duplication occurs, I believe that the information in the docs should be used (and referred to) and wiki information changed to reference the docs, rather than keeping information in multiple places.

I want to acknowledge that my opinion on this is not necessarily that of the rest of the community, and that others like to see more complete information on the wiki, at the cost of some duplication.

With regards to the Lots issue, I think that in the longer run, the Concept of Lots page should be removed altogether from the wiki, and any remaining special information on it should be put into the Guide in Chapter 9. Such an action would require someone to go through both, and incorporate information from the Wiki page into the existing chapter in a meaningful manner. I also believe that the Guide section “Selling Shares” covers gains and lots in MUCH greater detail than the original FAQ entry ever did. I recommend that you take a closer look at it. That was why I opted to remove the Wiki text altogether.

In regards to Uservoice, there already is a reference on the wiki to it. If you look at the main Wiki page under “Filing Bugs and Enhancement Requests” you will see reference to the Uservoice page. It would probably be nice to improve the visibility of that link. Such a change will require a special request, however, as the main Wiki page is locked from Edits by Mortals. Or were you proposing adding that link to www.gnucash.org <http://www.gnucash.org/>?

David T.

> On Jan 22, 2018, at 2:11 PM, Alen Siljak <alen.siljak at gmx.com> wrote:
> 
> Thanks, David. I'm refraining from deleting any text unless it is glaringly obvious that it is wrong.
> What I'm trying to do is to link various related pieces of information together. As you say, sometimes it can be contradictory because one side is quite outdated. I believe that, with having links, this would become easier to navigate and eventually correct.
> Sometimes I run into a page describing some concept and I can not find it afterwards.
> Multiple entry points to documentation are also extremely confusing to me - faq, wiki, user docs, doxygen, txt files, descriptions in the repo, etc. So, I guess, the ability to clean up is equally important as adding new text. :)
>  
> The Lots Concept guide page, which I linked to the Concept of Lots wiki page, contains the most complete explanation of the lots concept and the *implementation*, which is currently in GnuCash. From that point it is very valuable although it may be outdated. And I never saw any link to that page elsewhere.
> It is a bit difficult (for me, at least) to distinguish between user and developer documentation. Because, as a user, I had terrible problems working with Lots - transactions would appear duplicate out of the blue, transactions would be split automatically, etc. None of what's happening was obvious until I read the mentioned description. So, once a few details were known, I had no issues with the Lots any longer. Not able to reproduce the issues I was experiencing before and report as bugs because now I don't remember the way I tried to do it instinctively.
>  
> In addition, it would be handy to have useful links on the home page. For example, Uservoice is missing and I think this is quite handy for end users to have input into the desired features. While it does not guarantee the implementation, at least it shows where the demand is.
>  
> Hope what I wrote here makes sense. These are mostly observations from my short recent experience and not a direct reference to what you wrote earlier.
> Thank you for making the changes you just did. This just proves that adding the links between related topics helps to clean up the things a bit. For example, someone who only reads the FAQ would have a different understanding of capital gains process than someone who happened to search for Lots and read a different page. Now, at least, they should be a bit more aligned.
>  
> Cheers
>  
> Sent: Sunday, January 21, 2018 at 6:35 PM
> From: "David T." <sunfish62 at yahoo.com>
> To: cicko <alen.siljak at gmx.com>
> Cc: gnucash-devel at gnucash.org
> Subject: Capital Gains FAQ entry
> Cicko,
> 
> I see that you have gotten involved in working on the wiki; fabulous!
> 
> I recently received a notice that you had edited the FAQ on handling capital gains, by adding a reference to the wiki page “Concept of Lots”.
> 
> Naturally, having received the announcement of the page change, I took a look at both the FAQ section and the Concept of Lots page, and found a number of problems.
> 
> First, the FAQ itself is quite dated, mentioning the status of gains as of version 1.8. Since the Tutorial & Concept Guide represents the most complete and up-to-date version of the documentation, I have added these references and removed the original paragraph.
> 
> Next, it goes into quite a bit of detail on how to enter gains—topics that are now covered in quite some detail in the Tutorial & Concepts Guide. SInce "9.7. Selling Shares” is so thorough, the examples given in the FAQ are both incomplete and redundant. Consequently, I am removing the example in the FAQ, and pointing to the Tutorial a second time, since it has so many detailed examples.
> 
> Finally, I wonder whether it is wise to link to the “Concept of Lots” page, as it appears to be a description of how the implementer of the Lots feature went about it. Some of this information does appear to be unique, however, so I didn’t touch your reference to it. Long term, I think the information on this page should be separated so that the technical, development, information was placed on a technical page, and the user-focused information placed in the documentation set.
> 
> Anyhow, I just wanted to let you know why I went into this section and changed it just after you had.
> 
> David