[GNC-dev] Long Term Documentation Directions

[David T.]

Adrien,

> On Sep 11, 2018, at 1:09 PM, Adrien Monteleone <adrien.monteleone at lusfiber.net> wrote:
> 
> 
> 
>> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel <gnucash-devel at gnucash.org> wrote:
>> 
>> Hello,
>> 
>> 
>> 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.
> 
> While the principles might not change, or even the name/label of certain buttons, the UI layout (where those buttons are, the fact that they are buttons instead of menu entries, etc.) will very likely change as the Gnome HIG is more faithfully implemented. But those code changes shouldn’t affect anything generally in the Guide, and should auto update the context help if it is drawn from the code itself. If not, then consider that attempts to corral GnuCash within the confines of the Gnome HIG, will produce such changes you’re thinking won’t happen.
> 

We are in general agreement here. My point was that any context help text, being based on the *actual function* of a given widget (and regardless of the form or broader context of that widget) is unlikely to change. Geert was concerned that embedding help text in code would shield that text from the editorial expertise of members of the Documentation Team. I was trying to point out that these texts, once written, are unlikely to need rewriting unless the actual functions change. 

I’ll note here that you seem to have the documentation model backwards, insofar as you suggest that interface changes wouldn’t affect the Guide. I believe that such changes would not affect the Help, whereas changes in the UI and the form and location of a given widget would definitely be reflected in the Guide, since that is where the descriptive explanation of GnuCash and its functions will reside. The Help would only consist of context help containing a sentence or two about that widget.

David


> Regards,
> Adrien
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel