GnuCash Draft Concept Guide, or, Whose WIki Is This, Anyway?

Sun Dec 3 03:50:08 EST 2017

Frank,

Thank you for your reply. 

I will start with an overall observation: I think that you and I see the GnuCash documentation realm in fundamentally different ways. 

I believe that the wiki and what I will refer to as the official documentation (defined as the Tutorial & Concepts Guide and the Help Manual) should primarily serve complementary roles, with information in the official docs taking precedence. To me, the wiki supplements the official docs. The wiki amplifies the official docs by providing information that is of limited interest to the broader community (such as methods for handling some esoteric accounting issue in GnuCash, or a technical issue on a specific platform). To me, information (such as the wiki glossary) should be removed in favor of material that is entered as part of the official documentation set.

I think that you see the wiki as a primary information source for users, and as such, you think it should contain its own more or less complete set of information about the program and its functions. I may be wrong about this, but I believe you have expressed opinions that seem to support this idea.

This means that information can be put in both the wiki and the official documentation without a problem for you. However, I do have a problem with keeping information in two places: it is a challenge to keep both sets of information up to date and in sync with one another—and it makes for more work for someone to maintain this synchronization. Your words below suggesting that the work is too much for you to manage only supports my point.

As for the specific example of the term “reconciliation’: You say that there is something missing from the documentation realm regarding this topic, and want to add information to the wiki and the glossary. I, however, see that Reconciliation has an entire section (4.4 in the Guide) dedicated to it. It is fully explained there as an aspect of Transactions. This section is also referenced in the chapter on Checkbooks, section 5.4. As you note, adding “reconciliation” to the glossary might be useful; that, however, doesn’t seem to me to be a legitimate reason to retain the Draft Concept Guide in its entirety.

On the issue of the Guide Glossary, I will note that this section is literally version 1, made completely based on the Wiki glossary and my own ideas of terms that could use definition for users. (I’ll note that I had thought that ‘reconciliation’ was a common enough term that it didn’t need an entry in the Glossary. I am happy to have someone suggest otherwise, and will take steps to add it to the Guide Glossary). Since the Guide Glossary was based directly on the Wiki Glossary, I felt that the Wiki Glossary was superceded, and thus I deleted most of the Wiki content and added a note to consult the Guide Glossary. You overrode that decision, and I respected your wish to retain the duplicated information (despite the fact that I disagreed and still disagree with your assessment). 

I will note that it was never my intention that this version be considered the final one, and I would hope that others in the community with vested interests and different perspectives might have taken it upon themselves to contribute to the enhancement of the glossary to make it more complete (i.e., with more terms in it) and more useful (as in ensuring that first use of terms in the documentation referred to the glossary where necessary). 

There are methods for others to bring such enhancements to the docs—either by learning how to edit and submit documentation changes (as I somewhat have), or by submitting documentation bugs. 

As for scanning the Draft Concept Guide for such keywords, if I were to consider taking on such a task, I would go through the current versions of the documentation for such terms, rather than a ten-year old version. As I noted in another thread recently, that doesn’t sound like something I would want to spend my time on, however.

Finally, the GnuCash Wiki (and GnuCash in general) is no doubt a better place as a result of your contributions, and as you know, I have been quite collaborative in making some of your contributions read more idiomatically in English. In a reflection of my priorities, I have focused my energies in the Tutorial & Concept Guide. Given our different philosophies regarding the documentation roles, I think it might be better if *I* were the one to drop out of the Wiki world. I seem mostly to stir up trouble.

David

> On Dec 3, 2017, at 1:26 AM, Frank H. Ellenberger <frank.h.ellenberger at gmail.com> wrote:
> 
> Hi,
> 
> Am 01.12.2017 um 04:55 schrieb David Thomas:
>> Frank,
>> 
>> I am struggling right now to find the right way to bring up the issue of the Gnucash Draft Concept Guide, which still resides on the wiki.
>> 
>> As you know, I have proposed on numerous occasions (most recently, two and a half weeks ago) to have these pages removed from the wiki, since they are out of date, inaccurate, poorly written, superceded, and can turn up in search results, giving users incorrect information about Gnucash and its features and functions. 
>> 
>> In that recent thread, four people responded to my request to remove the Draft Concept Guide. Only you appeared to support retaining these pages, although your primary concern was with the mechanical aspects of Google’s search algorithm, upon which I have no expertise to comment. (I will note that fixing one search engine result set does not preclude some OTHER search engine now or in the future from finding and returning these pages despite your best intentions). 
> 
> I asked you for your search patterns, which resulted in that pages and
> was still waiting for a response.
> 
> IIRC only the google bot is allowed to crawl the pages. Ask Derek for
> robots.txt.
> 
>> You actually offered to move these pages to your own user area, but John noted that might not actually hide the results.
>> 
>> Two days ago, I went to the wiki to search for information about creating reconciliation reports in response to a question on the user list, and when I entered “reconciliation” into the wiki’s OWN search box, 4 of the first 5 hits were for the Draft Concept Guide.
> 
> Thank you for this search pattern!
> 
> 1x FAQ (a special case)
> 4x Concept Guide draft
> 2x Announcement (a minor change)
> 1x Project and Design Documentation (Casimonos approach from 2014,
> technical)
> 
> It should be clear, wiki search will not include docs - or knows someone
> a trick?
> 
> But my conclusions whould be different from yours:
> 
> An recent entry for "Reconciliation" is missing in - both versions: wiki
> and docs - of the glossary (your domain) with links to the respective
> chapters.
> 
> Before you remove probably outdated text, you should create a proper text.
> 
> Your domain, because I am tired to explain after every edit e.g. the
> relation between SheBang, MIME and GnuCash, it's helper scripts and
> Windows failing to run them.
> 
> IMHO instead of overwriting it now, you should scan it for the keywords,
> which are missing in the glossary and add sections there with links to
> their documentation.
> 
>> Since there had been no support for your position to keep the pages, and since you had had two and a half weeks to take whatever action you had proposed to do (and not taken any), I felt it was time to address the Draft Concept Guide issue directly. 
> 
> I was still waiting for your search expressions and there were more
> important things in between like the finance.yahoo issue.
> 
> Now I tested your pattern "reconciliation gnucash" with google, yahoo
> and bing and everywhere
> https://www.gnucash.org/docs/v2.6/C/gnucash-guide/txns-reconcile1.html
> and other pages of docs/v2.6 were listed before
> https://wiki.gnucash.org/wiki/Concept_Guide_draft/
> and as everybody knows drafts are not mandatory.
> 
>> I did not delete the pages outright (since I do not have the rights to do that), but I did what I considered to be the next best thing, which was to replace all the text in those pages with the latin nonsense that printers have used for hundreds of years to mock up page layouts (“Lorem ipsum”). I even made sure to retain the various structural elements in the pages, going so far as to replace headings and bullet points with latin phrases of similar length.
> 
> You overwrote the several linked images. Did you check their types: File
> or Link?
> 
> If they were files, are they linked by something else or should they be
> droppped, too?
> 
> This could later rise similar questions as in
> https://lists.gnucash.org/pipermail/gnucash-devel/2017-October/041152.html
> 
>> Since, as far as I understand, your only reason for retaining these pages is to serve as some sort of model for the Gnucash community to use for wiki pages, my technique allowed these model pages to be retained *without* their turning up in any search results, anywhere. So, that’s the best of both worlds, right?
>> 
>> Apparently not, as within hours, you had gone and reverted all my changes.
> 
> Yes, without breakfast I had to act. ;-)
> 
> I wonder, why you fill an empty page (Loans) with 6k "Lore ipsum".
> 
> It was no pure reversion. But I needed some time to investigate Adriens
> previous suggestion
> https://lists.gnucash.org/pipermail/gnucash-devel/2017-November/041263.html
> which resulted in a __NOINDEX__ in the template and a division
> "'''This text is outdated.''' See https://wiki.gnucash.org/docs.phtml
> for more recent versions."
> This appears now on  the whole set of pages.
> 
>> So, I have a few questions to ask of you, Frank, and of the community.
>> 
>> 1) First, Frank: What exactly is so special to you about these pages? Why do you insist that they remain forever on the wiki? The only reason I have heard from you is this idea that the pages could provide wiki page template examples. But, my most recent changes preserved the template aspect without retaining the problematic language—and you still reverted the changes. So, there seems to be something *else* with these pages that makes you feel so protective. What is it? My recent changes seem to prove that there is something in the text itself that you are attached to. Can you explain clearly what that attachment is?
> 
> It seems the guys working there a decade ago were in some aspects more
> advanced in wikimedia technics than we both together. ;-)
> Use of stylesheets, templates, subpages, file linking are the most
> prominent.
> 
> At least for me such methods are easier to adapt from such an example
> page than from
> https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents
> 
> I have started some time ago with
> https://wiki.gnucash.org/wiki/Wiki_Tips#Using_Images
> LeeRead added a few more aspects.
> 
> Add sections for each aspect mentioned above. Take the examples and add
> some context from mediawiki's help.
> After that we can discuss the removal.
> 
>> 2) Frank, in the past, you have chastised me for reverting changes that you had made on wiki pages, and informed me that it is considered rude to do so. So, why are you so consistently rude to me? This is not the first time that you have reverted my changes.
> 
> And yes, with the exception of the spammers from earlier years, you are
> the only person, where I had to use revert. :-(
> 
> To be more precise, I reverted changes where you removed mayor parts of
> the content.
> 
> And readded your additions. That was much easier than reentering the big
> sections which you had removed.
> 
> And added a section with my reasons to your talk page. That is the way
> how collaboration on wikis usually is done.
> 
>> 3) To the community: Whose Wiki is this, anyway? I have presented to the community on separate occasions my reasons for wanting to remove these pages, and I have heard from most of the developer community that these pages could be removed. The only person opposed to this appears to be Frank. However, Frank’s wishes on this issue (and others regarding the Wiki) apparently take precedence over everyone else’s, such that if Frank doesn’t agree, then it won’t happen. That doesn’t sound much like a collaboration.
> 
> If you weight each answerer with the number of it's wiki contributions,
> I still keep the mayority.
> 
> OTOH I am also happy, if you ask to mass revert all my edits of the last
> decade because I am slowly becoming tired. ;-)
> 
>> 4) To the community: Again, I put the question to the group: what purpose and procedures are supposed to apply to the wiki? There appear to be numerous unwritten rules about how to engage with the process (see for example question 2), and apparently I have broken those rules in this and other cases. It is frustrating to be encouraged to contribute to the wiki only to have those contributions rejected summarily. Establishing clear procedures and guidelines for contribution and workflow management seem to be in order—certainly if you expect non-developers to contribute back to the GnuCash community. 
> 
> Contribute, not detribute. ;-)
> 
> Until now there was no need for more rules than common sense.
> 
> E.g. I avoid to change OS/Distribution specific pages because they have
> more expirienced experts.
> 
> I am always happy, if somebody fixes my typos or improves my wordening
> because I am no native speaker...
> 
> There are so many themes lacking any documentation ...
> 
> 
>> Sincerely,
>> David T.
>> 
> 
> FRank