[GNC-dev] Main WIki Page edit

John Ralls jralls at ceridwen.us
Mon Aug 20 22:50:14 EDT 2018


Adrien,

Neither “clarification” is correct.

The “Tutorial and Concepts Guide” contains a *very* basic introduction to double-entry accounting, enough to get a new user going if all they have is a simple bank account and credit card. The rest of it is “how-to” on using GnuCash to perform some more complex tasks like managing capital gains and the business module. The emphasis is on using GnuCash and understanding its quirks. Mostly GnuCash tutorial with an introduction to concepts. 

The “Help Manual” is called that because it’s the document underneath the context-sensitive help; it has detailed explanations of some of GnuCash’s windows and dialogs, on the “this button activates foo, the buttons on this radio control selects which sort of bar you want” level. It’s strung together to form a document, but it’s not the sort of thing one would want to read like a book. There’s nothing at all about accounting in it.

Regards,
John Ralls

> On Aug 20, 2018, at 5:55 PM, Adrien Monteleone <adrien.monteleone at lusfiber.net> wrote:
> 
> Nice.
> 
> How about this for a tad more clarity on the two official documentation items:
> 
> * [http://www.gnucash.org/viewdoc.phtml?doc=help The Help Manual] - a quick reference manual for ~~specific~~ _basic accounting_ tasks, and
> * [http://www.gnucash.org/viewdoc.phtml?doc=guide The Tutorial and Concepts Guide] - an in-depth guide ~~to the concepts~~ _on using GnuCash to implement specific accounting concepts_. It is highly recommended to read at least the ~~first chapters~~ _Getting Started section_ of the guide.
> 
> That last edit of course could be more specific with a number of chapters, especially if the recommendation is beyond Section I. My point is just that ‘first chapters’ is a bit vague. (ideally, users should read it all of course, save maybe the business or investing sections if they aren’t applicable.)
> 
> Regards,
> Adrien
> 
> 
>> On Aug 20, 2018, at 7:30 PM, John Ralls <jralls at ceridwen.us> wrote:
>> 
>> 
>> 
>>> On Aug 20, 2018, at 6:57 AM, David T. via gnucash-devel <gnucash-devel at gnucash.org> wrote:
>>> 
>>> 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.
>> 
>> An excellent start, but I find the “Documentation for Users” section to be a bit stilted, so I’ve changed it to
>> 
>>> === Documentation for Users ===
>>> GnuCash offers two primary instructional documents: 
>>> * [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 that new users read at least the first chapters of the ''Guide''.
>>> These are accessible via the '''Help''' menu in the program (if you've installed via a package manager you may need to install an additional package called something like "gnucash-docs") and from the [http://www.gnucash.org/docs.phtml Documentation page on the gnucash.org ''website''].
>>> The ''Help Manual'' is available in English, German, Italian, and Japanese; the ''Guide'' in English, Italian, Japanese, Portuguese, and Russian.
>>> 
>>> ''PDF'', ''ePub'', and ''mobi'' formats may be downloaded from the [http://www.gnucash.org/docs.phtml Documentation page] where you will also find the documentation for earlier releases and a nightly build of changes made since the last release.
>> 
>> This also adds information about where to find it (it’s included in the program with all of the transalations) and ditches the overly technical use of the language codes in favor of writing out the names of the translation languages.
>> 
>> The Russian translation is partial and the translator seems to have run out of steam on proceeding, but it includes the first few chapters so I’ve included it. I’d forgotten to ensure that the built docs actually got uploaded and to add the links to the website; I’ve just done that now.
>> 
>> 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



More information about the gnucash-devel mailing list