[GNC-dev] Long Term Documentation Directions

[David T.]

Hello,

> On Sep 11, 2018, at 4:45 AM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
> 
> 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 :(
> 

Geert, you note that the developers are not proficient documentors, and I agree with you. You also say that you’d prefer the broader documentation team (such as it is) to be able to edit this context help.

One major reason for my suggesting that context help be embedded in code is a direct response to the current situation, where well-intentioned documentation contributors have placed duplicative information in *different places.* Deciding when a “small piece of prose” (as you put it, Geert) crosses that magical threshold from context help into concept guide is precisely what has led this documentation into the mess it’s in. Although it’s perhaps heresy, I think that limiting the ability of the Documentation Team to make contributions to the Help might not be a bad idea. Push everyone to the Guide, instead.

I envision that the context help would consist of short _functional_ descriptions of one or two sentences. I believe that the rate of change in the functions of the UI elements is exceedingly small. In my decade-plus time using GnuCash, I haven’t seen many changes to the buttons or screens. Accounting hasn’t suddenly come up with an entirely new set of functions. This leads me to the conclusion that functional descriptions of those buttons and screens won’t need to change either. If the functional aspects of the interface don’t change, then the context help doesn’t need to change, either. If the content isn’t changing, then the authorial skill of developers is beside the point. 

In other words, unless there is a change in function, there is no need to change the functional description. It seems to me that putting text that doesn’t change into code is essentially a one-time process. Not necessarily easy, but once completed, not particularly obtrusive. Putting the functional description into code has the added benefit, perhaps, of alerting developers to the fact that if they change a feature, the description (right there in the code) needs an update as well.

> 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.
> 

Keeping in mind that the Help is meant to be *contextual*—that is, linked directly to the screens and widgets a user encounters in GnuCash—perhaps the Help document should be more strictly structured to reflect this. Set it up as a table, with a column that provides the link to the interface, a column for the (brief) help text, and a column to link to the guide. This sort of structure exists already in some places of the Help; converting the entire document to this format would make clear to future writers and users that the Help is primarily meant for access from the application. People looking for more explanation would be directed to the Concept Guide. In an absolute sense, there is no real need for chapter headings, screen titles, figures, etc., since user access to this document would strictly be from the application itself. You could, I guess, go the other direction, and create separate files for each individual entry. To me, madness lies down that alley.

> 
>> 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.

What David describes here is essentially what we are already doing, I believe? 

David T.