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

[Adrien Monteleone]

> 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