[GNC-dev] Long Term Documentation Directions

Geert Janssens geert.gnucash at kobaltwit.be
Tue Sep 11 04:45:03 EDT 2018


Op dinsdag 11 september 2018 09:15:43 CEST schreef David Cousens:
> David,
> 
> Just some comments on a couple of other points:
> 
> Embedding even the context help in the program code is not a really good
> idea. It means that text cannot be edited /altered easily separately from
> the program and without rebuilding the program. 

You raise a good point here. Aside from the building restriction (which we now 
also have for source message translations), it would probably limit the 
potential help writing contributors to only those people capable of parsing 
the source code. In practice there would be few outside of the developers 
themselves. And those are known not to be the best documentation writers :(

So I vote for keeping all help consisting of more than a single sentence in a 
separate document. So a short tooltip or a hint in an empty text entry go into 
the code (also for practical reasons), but a small piece of prose explaining 
how a certain dialog window works should go in a document that is more easily 
edited by documentation writers.

What we may be able to do is write some scripts that would automatically 
extract a list of all user interface elements from the source code and compose 
a skeleton document from this. Then with some clever msgmerge like magic merge 
existing help strings from a previous version of this document. That would at 
least make sure the list of interface elements can be kept up to date 
programmatically so no one should scan the sources manually for changes.


> My understanding is that it
> can be done from a docbook that just has the links to a section which is
> displayed in response to a help button being pressed or  something like a
> Shift-F1 key combination while the focus is on the button/checkbox/etc that
> you want help on. It could be a separate window from the main help system
> which just pops up displays the information and closes when you finish (i.e
> no navigation - want help on something else-click on something else and hit
> shift F10 -  but pulls its text from a HTML file created from a
> docbook/asciidoc or similar source help file. It would not necessarily have
> to have such a file broken up into subfiles.
> 
> The same would also be true of the Concepts guide. It could be modules
> within a single file or a collection of files which can either be displayed
> independently or linked together to form a full document. The existing Help
> manual are organised a bit like that but the separate files for the chapters
> do not have document headers so they can't be displayed independently .
> What I mean by that is you can point a browser at the derived HTML file for
> a chapter and have it display just that chapter without having to load the
> whole Help manual and navigate to the bit you want. In any case breaking it
> into separate source files is not a high priority but it may make some
> sense to have related content in its own module futher down the track. It
> can also be done progressively once the content  has been rearranged.
> 
Indeed. We should primarily find a way it remains manageable for translators.


> Walk throughs on the other hand require a considerable code effort and have
> to be embedded in the code completely. They need an engine which can drive
> the interfaceand either feed data in or better still request the user to
> enter the data.  The one I am most familiar with is in the Flight Gear
> flight simulator on Linux. It is just like a flying instructor taking you
> through the check list before takeoff. While it would be nice I doubt if it
> would really be feasible.
> 
Agreed. Walk throughs ad described on the link David passed are not planned in 
the foreseeable future. What I was hinting at in my suggestions is more 
documentation formatted as explained in:
https://www.youtube.com/watch?
v=7amYpQWhz3o&index=57&list=PLaVkMRyQacUQYxXkzvcZJm-kc_FEJpkxK&t=0s

But to be clear: I won't be doing the documentation restructuring/writing, so 
neither will I dictate what format and content the guide should be. I'm fine 
with the current high level proposals.

I do care about maintainability beyond the initial restructuring/rewriting 
effort so if I find issues in that area, you'll hear me :)

In that context I think we should make documentation translation a separate 
thread. The current one is getting hard to follow.

Regards,

Geert




More information about the gnucash-devel mailing list