Getting the right amount of help in Gramps

Gramps can be intimidating, even for long-time users. We do have many Help buttons that bring up wiki pages in a browser.

But I feel that the wiki pages can be overwhelming, or underwhelming. And they may not be translated into your language.

I’m thinking of a different system that:

  1. Is brief, and specific to a particular UI item or window
  2. Is translated to your language
  3. Easy to find; at your fingertips
  4. Built into Gramps

As a first example, I’ve added an :information_source: button in the upper-left hand corner of the Date entry window. Here is the window shown in two languages:

In English:

And in French (the text hasn’t been translated yet, but check out the date entry syntax examples):

The top half of the information is helpful in general (what does the “Calendar” selection do; what is “dual-dated”) but the bottom part shows how to enter date variations in your language.

[Why would this more likely be in your language than the wiki page? It would be translated by Weblate. These texts are seen and translated by a large group of people]

Helpful hints like these have become more important with the introduction of new languages planned for inclusion in Gramps 6.2, including:

  • Japanese
  • Korean
  • Chinese
  • Vietnamese

But I know it is useful for me already.

Where else could Gramps use brief, specific help hints?

Honestly, I think that we need to have a bigger discussion about the wiki. If that is the official help and manual of Gramps, then it desperately needs a refresh. I agree that it is both over and underwhelming, but it seems like this would be duplicating work. If there was a way to make sure this matched the wiki, or was pulled from there, that might prevent another area of possible mis-matched information.

I 100% agree! I didn’t necessarily want the “info project” to be anti-wiki, but in my honest opinion, if users have to go to the wiki, then we’ve lost. It has a number of issues:

  1. It looks like an interface from 1995. It is jarring at the most visual level
  2. It doesn’t get updated nearly enough
  3. It is a real burden for translators to work on. It has far fewer translations than the strings in Gramps (understandably)
  4. Every page needs updating, causing all translations to be outdated

Maybe we move away from the wiki and focus on smaller, specific chunks of text that can be more easily discovered and translated by translators? We don’t have to answer that now; let’s see how this works for some smaller portions of Gramps. But I certainly have your question at the top of my mind.

I think this is a brilliant idea.

We already have hover-over pop-ups for most of the fields, but these will seldom explain the context of the content of the window.

Many users prefer try and error in stead of RTFM. For these users an :information_source: button is just what they need to go forward.

Of course the criticisms of the wiki in no way diminish all of the work people have done to write and organize all of that! It is not a criticism of that work at all, but of the process. In fact, I used the wiki as a starting point in crafting the info message in the above Date entry page.

  1. Search is awful because all translations are in the same ‘space’
  2. The wiki is a mixture of user guide and reference manual, which should be separate

Thank you for pointing out these issues @csam! It suggests a slightly different architecture than exists in the above Date editor PR. It suggests these questions:

  • What if the info texts could be assembled into a translated doc?
  • What if they were searchable inside Gramps?

And on a related note suggested by @emyoulation : what if the text supported markdown? That would allow a richer presentation than just text.

I did some exploring in Gramps:

  • There are 29 editors
  • There are 28 other dialogs

If all of that text could be broken into short paragraphs translated by Weblate, and the dialog help text could be generated when needed, you could have a searchable, markdown-based set of “pages” that could also form the basis of a document—all in the locale language.

I refactored the Date widget info system to:

  1. be able to be used in a search function
  2. possibly used to generate docs
  3. use markdown (thanks @emyoulation for the idea!)