Troubleshooting Section?

[james]

On 09/13/2016 05:08 AM, Geert Janssens wrote:
> On Sunday 11 September 2016 07:46:04 John Ralls wrote:
>>> On Sep 10, 2016, at 10:49 PM, David T. via gnucash-user
>>> <gnucash-user at gnucash.org> wrote:
>>>
>>> Being a long time user of GnuCash and subscriber to this list, I
>>> have experienced firsthand and seen others struggle to get various
>>> aspects of GnuCash working or fixed. Many times, the solution is
>>> found by searching the list history, or by consulting the Wiki.
>>> This is not something that is apparent to many new users of the
>>> software.

+1

>>>
>>> I wonder whether it would be useful or productive to create a
>>> separate Troubleshooting section in the Tutorial and Concepts
>>> Guide, with chapters covering broad areas of the software, that
>>> address some of the more common issues that come up.
>>>
>>> Thoughts?

I recently needed to upgrade from 2.4.11 to 2.6.13, as I use Gentoo 
linux. There are snippets of suggestions all over the docs. Migration
as simple as one version to the next to migration from one major version 
to the next, is platform specific, in many cases. Then there
is the issue of migration from one machine to another, or one machine
to a cloud or a local cluster, VM on container. It is a topic that 
should be in a completely separate document, imho. A general structure
to the isssue, then chapters (some rich, some TBD) per different types 
of scenarios, would be a much better way to organize such a commonly 
used document.

Another valid section would be interoperability and data migration 
between commercial offerings (quickbooks etc) and other open source 
platforms should at least warrant a chapter on it's own and not 
sprinkled about like seasonings on a holiday feast.
I guess what I'm say is consolidation by platform, then relevance to a 
specific subtopic is a filter that the entire documentation set(s) need 
to become better organized.

I would be willing to participate in such documentation upgrades, if the 
project is serious about cleaning up the current document offerings.
Keep the old and the new docs around until the new docs completely 
subsume the what good about the old(current) docs.
The current documents looks as if random random tidbits are strewn 
about, that may or may not be useful. Much of the documentation is quite
dated. I also installed the documentation package "gnucash-docs", 
determined it was 'docbook' and have no idea what needs to be done to
these documents codes to display a useful help-guide. Maybe the gentoo 
dev did a poor job or maybe a generic write up or reference on how to 
complete the installation and use 'docbook' files is not properly 
packaged up and explained. Regardless, I have not yet discovered how to 
use the documents inside of this package either.

In short, it just looks like the documents need an overarching theme
and consistency so they 'flow' one to another and there is a provision 
for newly discerned information and details, per platform, to be made 
available for users to provide new an relevant experiences to the docs.
Maybe not formally but as current addendum or current examples or 
current issues. Good information is buried in the ML and elsewhere and 
is never filtered into a form for easy retrieval, imho.
I'd suggest separation  of Windows from linux, for starters. Leverage 
the CLI method and CLI syntax, but link to gui or tool interfaces that 
are relevant when available. Screenshots are nice too, particularly for 
Windows users.

Another idea is a User Tip section, distro specific, where users can 
easily include new tidbits and examples, with a 'caveat emptor' warning,
until the information can be formally reviewed and integrated. The docs 
main issue is 'adhoc' and 'sporadic' attention, rather that proper 
maintenance. Like it or not, documentation in open source is keenly
important, as there is no helpline. Perhaps listing a set of low cost
consultants that charge by the 15 minute cycle to help users for modest 
fees, realtime, is another venue to give users choice and better support?


  Also, maybe every 6 months the user experience addendum could be 
parsed for formal inclusion into the formal documents, just to keep them 
fresh and relevant.  Call is a documentation update day and routinely 
schedule it for long time users and devs to all pitch to review things 
and devote part of one day for fixes, clarifications and updates. Even 
once a year would be a keen idea, imho.


hth,
James




>>
>> I'd think that that would work better on the wiki than in the static
>> documentation; in fact the FAQ page has a lot of troubleshooting info
>> already.

>
> The FAQ has a lot if troubleshooting info indeed. However I believe in it's current form it's
> difficult to query. I think the FAQ has become too long to be practical and not really well
> structured. I can imagine people look at it and get lost quickly.

+1

>
> Note the FAQ starts with "The contents of this FAQ will eventually be merged into the official
> GnuCash documentation" which actually encourages David's idea...
>
> My primary reservation is duplication of effort. Having both a FAQ and troubleshooting
> documentation in the guide means both have to be maintained. From experience I see the wiki
> has a lower barrier to contribution than the static documentation has (for all good reasons).
>
> If we decide to each troubleshooting item in either the faq or the static documentation, the
> burden is moved on the user's shoulders who now has to search two places to get help.
>
> Having said that I'd welcome a higher quality kind of trouble shooting guide for users. Perhaps
> John's suggestion to do this on the wiki may be a good first experiment.

+1. Use the wiki for concurrent feedback of information, current issues 
and examples. Centralized issues and sectional guide should be in a 
formal document, particulary things that do not change across major 
revisions. The minutia of current and platform specifics should be 
concentrated in the wiki. Users should have a mechanism to add current 
examples to the wiki too.  Periodically scan/filter the wiki for formal 
revisions to the main, offcial document(s).

Split windows from linux, or at leat put them in separate sections of 
the documents, even when similar. mixing windows and linux manuals 
rarely works, and is often the source of great confusion, when a windows 
user only knows a little about about linux (enough to get them in 
trouble). If you have to mix windows with linux, limit it to *buntu.

hth,
James


>
> Regards,
>
> Geert
> _______________________________________________
> gnucash-user mailing list
> gnucash-user at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-user
> -----
> Please remember to CC this list on all your replies.
> You can do this by using Reply-To-List or Reply-All.
>