Need suggestions for documenting the GTK chooser

The idiosyncracies of the GTK file chooser used throughout Gramps has sparked confusion leading to a number of support issues.

I know that the feature needs to be fully documented in its own wiki page. Nuggets of information are scattered, there is conflicting & incomplete introductory material in different places. It has to be consolidated and introduced in a structured way. Then the wiki has to be searched and cleaned so that all references (including the linking into a new GUI Gramps Glossary entry) point at the new consolidation.

But it will be such a different page that I’m waffling over HOW it should be structured.

I need thoughts & direction. (There’s already a missing page hotlinked added in the latest revision to the example.gramps page. So building a page has to be hurried before someone creates a sketchy patchwork just to fix the broken link.)

It might follow the How do I…? tutorial template. But I’d like it to be cleaner and far less complex.

I know that it needs to cover:

  • GUI differences between Dialogs for Linux, Windows & macOS OSes
  • URI & network support differences between OSes
  • themes and the GUI
  • switching between breadcrumbs & filepaths (including changing the default)
  • relative paths for User Data & application data
  • the difference between GTK file chooser and and OS file chooser
  • customizing bookmarked folders
  • cross pollination between GTK driven applications and customizations of the file chooser
  • keybindings (hotkeys, keyboard shortcuts)
  • persistent paths
  • link to developer docs (GTK generic & Gramps specific)

What else?

By the way, this GTK file chooser document is for missing foundation material needed for improving the example.gramps documentation. And that document improvement was needed before fixing the beginner Import & experimentation documentation.

Every time work begins on improving the New User experience, foundation material is discovered to be missing.

The most frustrating piece that is missing are the absent GUI icon illustrations. Without them, describing use of the GUI is incredibly painful. (And that pain is multiplied dozens of times … for each of those icon verbal metaphors have to be translated.)

But the process for filling them in is undocumented. And we’ve got a roadblock in getting that resolved.

The implementer of the template has determined the wiki needs a new technology… so filling the current template in will require a lot of work that would be discarded. (Plus the current template puts undue burden on the server.) But the new tech requires webmaster do significant (and RISKY) work in iterative updates to the 2018 vintage MediaWiki installation. And those updates are NOT cooperating.