[GNC-dev] Long Term Documentation Directions

John Ralls jralls at ceridwen.us
Tue Sep 11 13:18:20 EDT 2018



> On Sep 11, 2018, at 10:09 AM, 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.

Why do you think we're going to "more faithfully implement" the Gnome HIG? One of our long-term goals is to remove our Gnome dependencies. 

Regards,
John Ralls



More information about the gnucash-devel mailing list