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 <jra...@ceridwen.us> wrote: > > > >> On Aug 20, 2018, at 6:57 AM, David T. via gnucash-devel >> <gnucash-devel@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@gnucash.org > https://lists.gnucash.org/mailman/listinfo/gnucash-devel _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
