[GNC-dev] Main WIki Page edit
sunfish62 at yahoo.com
Mon Aug 20 16:02:37 EDT 2018
Thank you for implementing the changes.
WRT removing the references to the glossaries, it *was* my intention to remove them, for a few reasons. First, the glossaries are sections of either the Guide or of the wiki. Thus, like the FAQ and the Using Gnucash links, it doesn't merit top level mention.
As I considered it further, it seemed to me that a glossary isn't really something that someone seeks out for itself; they will only seek it when they don't understand a term they find elsewhere. Thus, my suggestion that these terms, when used, should receive proper linking in the source. Moreover, given that the Guide is separately released and published, I felt that mention of the Guide Glossary in the wiki was truly superfluous--akin to making note that the Guide includes screenshots. Therefore, mention of the Guide Glossary was out.
As to the Wiki Glossary, I rather liked Adrien's suggestion that such mention might go with developer info later on the page. Since I wasn't focused on those other sections, I set aside that change, and then I later decided that inline citations would be the better solution. Thus, no more mention of that glossary from my corner.
On the subject of the different sources for information:
It may be advisable to put a note about differences between the documents. However, any discussion about the information on the wiki versus the documentation needs to be couched in terms that explain the differences clearly, fully, unambiguously, and without bias. IOW, the wiki might be more recent, but that information is more likely subject to change, since it may not be fully accurate. The Help and Guide have been edited for accuracy.
On August 20, 2018, at 10:38 AM, "Frank H. Ellenberger" <frank.h.ellenberger at gmail.com> wrote:
I have applied it, but have 2 questions:
Was it intended to remove the reference to the glossary completely?
Should we somehow note, that in doubt the wiki might be more recent than
the official docs?
Am 20.08.2018 um 15:57 schrieb David T. via gnucash-devel:
> OK. I have looked over this issue with an eye to clarifying the text, and I believe that the User Documentation section should be simplified. As currently written, as you all have noted, the User Documentation section includes different layers of content, presented at the same tier of coverage. Thus, the Help and Tutorial are presented alongside two wiki pages and two glossaries. That’s inconsistent.
> So, first up is to level things off. That means eliminating the separate headings for the Glossaries, the FAQ and Using Gnucash, and changing the main section to refer to the wiki at the same level as the Help and Tutorial. In the interest of helping people in dire need, I choose to retain the references to the FAQ and Using GnuCash pages, but as a descriptive list under the wiki in general (I will note that I also changed the Getting Help page to parallel this approach). As suggested, mention of the Glossaries isn’t particularly appropriate here, so I remove it altogether. [FWIW, I think the proper approach would be to make sure that all uses of special terminology in the wiki and the documentation receive reference to their glossary definitions, ideally as tool tips—but that solution is beyond my ability]
> I also don’t like “User Documentation” since we aren’t documenting users, so I prefer “Documentation for Users”, which requires the following heading to be changed to “Documentation for Developers”
> Here is my final suggestion for the section in question:
> === Documentation for Users ===
> GnuCash offers two major pieces of documentation:
> * [http://www.gnucash.org/viewdoc.phtml?doc=help The Help Manual] - a quick reference manual for specific tasks, and
> * [http://www.gnucash.org/viewdoc.phtml?doc=guide The Tutorial and Concepts Guide] - an in-depth guide to the concepts. It is highly recommended to read at least the first chapters of the guide.
> The [http://www.gnucash.org/docs.phtml Documentation page on the gnucash.org ''website''] also contains these documents in
> * '''other languages:''' de, it, ja, pt;
> * '''other formats:''' ''PDF'', ''ePub'' or ''mobi''; as well as
> * '''other releases:''' nightly (unstable), previous and earlier stable releases.
> The GnuCash wiki includes extensive information regarding all aspects of GnuCash, contributed by the developers and users of GnuCash. Information in the wiki covers a broad variety of topics, and includes detailed technical information, as well as information that applies to specific use cases. Of particular interest on the wiki are:
> * The [[FAQ|GnuCash FAQ]], which contains a collection of frequently asked questions about GnuCash, including administration, accounting, and glossary questions, and
> * [[Using GnuCash]], which collects real life experiences using GnuCash. You may find (user) solutions here that are not covered by the documentation.
> === Documentation for Developers ===
More information about the gnucash-devel