[GNC-dev] Main WIki Page edit

Mon Aug 20 09:57:15 EDT 2018

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

> On Aug 18, 2018, at 8:53 AM, D via gnucash-devel <gnucash-devel at gnucash.org> wrote:
> 
> The glossary entry has historically been included separately on this page. When I last suggested changes for the page, it didn't occur to me to remove that separate section and incorporate references to them (there are two glossaries: one in the Guide, and the one on the wiki, each with slightly didn't vintage) in other locations.
> 
> Incorporating these references into other sections makes sense to me. It simplifies the main page structure a little, and reflects the fact that the glossaries are part of the Guide and wiki, respectively.
> 
> I'll look into a rewrite, and send it in for adjustment in the next few days.
> 
> David T.
> 
> On August 18, 2018, at 7:15 AM, Adrien Monteleone <adrien.monteleone at lusfiber.net> wrote:
> 
> In combination with making the T&CG glossary sentence a part the Official documentation paragraph, I think the second sentence should be moved down to the Developer Documentation paragraph.
> 
> Also, the following line needs a number correction:
> 
> "The Documentation page on the gnucash.org website also contains ~~this~~ _these_ documents in”
> 
> I’d do either myself, but I see the main page is above my pay grade. (I’m sure for very good reason)
> 
> Regards,
> Adrien
> 
>> On Aug 18, 2018, at 8:53 AM, John Ralls <jralls at ceridwen.us> wrote:
>> 
>> 
>> 
>>> On Aug 17, 2018, at 11:45 PM, David T. via gnucash-devel <gnucash-devel at gnucash.org> wrote:
>>> 
>>> 
>>> 
>>>> On Aug 17, 2018, at 11:29 AM, Frank H. Ellenberger <frank.h.ellenberger at gmail.com> wrote:
>>>> 
>>>> Am 16.08.2018 um 20:37 schrieb David T. via gnucash-devel:
>>>>> Hello,
>>>>> 
>>>>> I was reviewing the Wiki today to try to figure out where a page on the SQL formats might get attached, and I noticed a change to the Glossary section that makes for awkward English.
>>>>> 
>>>>> As currently entered, the section reads:
>>>>> 
>>>>> Above GnuCash Tutorial and Concepts Guide includes a comprehensive Glossary: [https://www.gnucash.org/docs/v2.6/C/gnucash-guide/gnc-gloss.html Released] or [https://code.gnucash.org/docs/C/gnucash-guide/gnc-gloss.html Maintainer] version.
>>>>> 
>>>>> However, it used to say:
>>>>> 
>>>>> The GnuCash Tutorial and Concepts Guide includes a comprehensive Glossary: [https://www.gnucash.org/docs/v2.6/C/gnucash-guide/gnc-gloss.html Released] or [https://code.gnucash.org/docs/C/gnucash-guide/gnc-gloss.html Maintainer] version.
>>>>> 
>>>>> I would like to ask that someone with edit permissions on the wiki home page to please change the word “Above” back to “The” to make the section read more idiomatically.
>>>>> 
>>>>> David T.
>>>> 
>>>> IMHO it is also bad style to have:
>>>> The Tutorial and Concepts Guide - an in-depth guide to the concepts.
>>>> :
>>>> The GnuCash Tutorial and Concepts Guide includes a comprehensive
>>>> Glossary: Released or Maintainer version.
>>>> 
>>> 
>>> We differ in our opinion here. I stand by my recommendation.
>> 
>> And you’re both right, it needs a more thorough rewrite to flow better. Since the glossary isn’t a stand-alone document it shouldn’t have its own level-two header. An additional sentence in the T&CG paragraph under Official Documentation would be better. On the other hand the wiki needs more prominence, there’s a whole lot more information there than just the FAQ and technical glossary.
>> 
>> Regards,
>> John Ralls
>> 
>> _______________________________________________
>> gnucash-devel mailing list
>> gnucash-devel at gnucash.org
>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> 
> 
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel