[GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org

[D.]

Adrien, 

Being a past member of group 1, I can vouch for the challenges that the current tool set presents. Some might even call me the poster child on how difficult it can be. It does meet numerous disparate needs, however. 

Your group 2 users can and do contribute-- to the wiki and the user list. Remember that the GnuCash "culture" is to recommend reading the docs, check the wiki, and check the mailing list archives. 

I agree that there are disconnects and gaps. For example, stuff seems to get into the wiki and never go any further-- and they often remain in the wiki long after the documents get updated. Similarly, mailing list threads rarely migrate. To me, this is where the significant disconnect lies: in the fact that ideas discussed here in the lists rarely go further to the wiki and the docs. 

Underlying this, I think, is a sense that the docs are incomplete or inferior or outdated, and the best way to answer a problem is to ask on the lists. The tendency in the community is to reinforce this sense, unintentionally perhaps, by repeatedly answering basic questions in lengthy email threads, rather than either referring users to the existing documentation or by migrating the knowledge in those threads into the documentation. I know that you've been active in taking this on, and that the other Diligent Davids have been working to get major areas of the documentation updated, so all is not lost!

David T. 
Former documentarian


-------- Original Message --------
From: Adrien Monteleone <adrien.monteleone at lusfiber.net>
Sent: Thu May 07 05:49:14 GMT+05:30 2020
To: Gnucash Users <gnucash-user at gnucash.org>
Subject: Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org



> On May 6, 2020 w19d127, at 5:53 PM, David Cousens <davidcousens at bigpond.com> wrote:
> 
> The existing tool chain meets more than the need for a single document. There
> is translation into multiple languages, online versions, standalone pdf,
> epub etc. The Read theDoc' format is certainly quite nice but to be a
> replacement candidate for the current tool stream it has to offer
> considerable advantages over the current process while still meeting those
> needs. Maybe these can all be met with an alternative but his needs to be
> ascertained.
> 
> The current documenters have invested time and effort in coming to grips
> with what we currently use. Replacing part of the current tool chain means
> we are going to have to put time and effort into learning a new approach
> when in most case our available time for working on the documentation is
> better spent exploring GnuCash and how it works and the underlying code. It
> is not as though we are particularly well resourced in this area.


Sounds to me like there are at least two perspectives here:

1. Current documenters who have invested in the current toolchain but don’t have all the info necessary to re-write the docs.

2. Users who can provide the info for documentation based on how the app works in their experience (at the user level, not necessarily at a code level) but who haven’t invested in the toolchain and for whom such an investment is out of their scope, wheelhouse, time available, etc.

There is clearly a disconnect and a gap.

How to bridge it?

I’ll posit there doesn’t need to be ‘one toolchain to rule them all’ though that isn’t precluded should such a solution be discovered.

Perhaps there should be another entry-point for Group #2 where they can submit documentation improvements on no simpler a basis than standard word processing, wiki editing, markdown etc.

Then Group #1 takes that revised or newly added text and “sausages it” through the current project-preferred toolchain.

Presently, either you join Group 1, or you don’t contribute and the docs stay stale or incomplete.

Non-techy users can ask questions and report issues here on the list, and on Bugzilla. Maybe some similar process should be outlined for documentation and not just for functionality. (I know one can already file documentation bugs, the point is to clearly spell out that a similar process for documentation exists, or will.)

Is there no room for offering Group 2 an easier point of entry? Is there an option which doesn’t require Group 1 to have to re-invest time in a different toolchain?

Regards,
Adrien

> I support Frank's approach of defining and documenting what it is the
> documentation currently does and needs to do then looking at what the
> advantages/disadvantages of any alternative approach to the current tool
> chain actually are and whether it can mmet all the current needs. In doing
> this we also need to examine who is currently working on the documentation
> and how they might react to a significant  tool change. If a major effect is
> we lose a significant part of the current resource base in this area, is it
> really productive to make a change unless that change is really necessary
> and increases the resource availability and productivity.  My time spent of
> documentation is less on working out the intricacies of DocBook and more on
> experimenting with GnuCash and exploring the code to ensure I understand
> what is going on. DocBook is not my personal limitation although my
> understanding of it is far from complete.
> 
> DocBook may not be as compact as asciidoc code but it is well documented and
> the tag structure does help in finding and isolating errors. It may be more
> productibve to go to DocBook 5 for example and enable a common glossary
> between the guide and help manual and facilitate better crosslinking.
> 
> The prettiness of the output may also be addressed by changes to the style
> sheets used to process the current docs which would not require a change to
> an entire codebase or change of tool chain.
> 
> David Cousens

_______________________________________________
gnucash-user mailing list
gnucash-user at gnucash.org
To update your subscription preferences or to unsubscribe:
https://lists.gnucash.org/mailman/listinfo/gnucash-user
If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
-----
Please remember to CC this list on all your replies.
You can do this by using Reply-To-List or Reply-All.