[GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op dinsdag 11 september 2018 15:13:51 CEST schreef 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.

Well, that's one way of looking at it. I think the main reason why we have 
duplication is because there hasn't been anyone who took responsibility for 
the documentation in years and perhaps there never was. Someone to set clear 
directions and guard them. Someone that would review contributions and direct 
contributors in the right direction.

John and I do this for the code, but there's no one doing that for 
documentation really.

As such I'm very pleased with your initiative to clarify the boundaries of 
documentation. And frankly I don't really care that much what those are in 
detail. As long as it works as a clear framework for anyone interested in 
contributing. And that it will be backed by a couple of people to guide new 
contributors. I understand you and David Cousens are willing to rework the 
existing documentation. Great! Are you also willing to review work done by 
others and tell them to relocate if their initial suggestion isn't right ?

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

As for the context help in particular, this discussion is too abstract for me. 
I have a feeling you and I are thinking of different things when we write 
about context help or how to handle it.

In addition I worry we're trying to change too much at once. You started with 
the goal of deduplicating content and for that you propose to move most 
content from help to guide. I'm all with you. I propose to do that first and 
*then* see what remains of the help document and decide what to do with it.

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

I mostly agree. However as I mentioned before there is a difference in how to 
manage the source and how to display the end result to the user. The sources 
can be one big table if you like. However it's less than user friendly to show 
that full table to the user when s/he's only interested in the particular 
button s/he wants to click on. Anyway I think it's too early to decide what 
the final format of the help document(s) will be. Focus on the guide first is 
my current advice.

Geert