LSMB Help Proposal

[neilt]

LSMB Help Proposal

This document proposes embedding all help and documentation into a running LSMB system for both users and developers using various parts of LLM (large language models), AI (artificial intelligence) and NLP (natural language processing). This proposal does not include merging the tutorial from the book into LSMB.

When someone needs to know something, instead of trying to figure where to find the answer, this proposal puts all of the answers in a defined location using either context based help or a focused ChatGPT like search and response process that does not access any external servers.

Why?

1. Eliminates wasted user time scanning or searching through the book trying to find help. While the book table of contents provides context, it is not very granular. The book index is granular, but does not provide context. In addition to the book, the wanted information may be on the website, in an FAQ, in the release notes, in an open or closed issue on github, in the code comments, in a github discussion, etc.
2. Easier to establish context. One problem with the book is that in order to document a fact, procedure, or explanation (hereinafter called help) and have it make sense, a context must be established. This takes additional time, which is often unavailable, and leads to delays in book updates. Sometimes this delay is infinite.
3. Help being provided directly to the user on the screen at the point it is needed is automatically in context.
4. This proposal will make help closer to the code and easier for developers to update help when the code changes.
5. Developers don't have to know LaTeX.
6. Documentation version is automatically matched to code version.
7. PDF files are easier to search, HTML files are not. By embedding search at the text level, in the source, some complexity is removed. Remember LSMB is primarily an HTML generator.
8. Using LLM, AI, and NLP is modern, popular, and will separate LSMB from the competition. This may also draw development resources to the project from people who want to establish their AI credentials.

Overview

The help subsystem will be comprised of both User Help and Developer Help.

1. User Help will always be available and is installed automatically.
2. Developer Help will only be available if the installer selected an option to install it. Most installations will not need developer help.
3. For context sensitive help.:
   a. If there is User or Developer Help available for a screen, a button will appear on the screen called something like "Show Help". When this button is turned "OFF" the view shows as it currently does. That is not showing any help icons. This reduces screen clutter for experienced users.
   b. When the "Show Help" button is turned "ON" the screen will show help icons next to each item where help is available. When the user clicks on a help icon, LSMB opens a pop up window (toast) with the localized help that is specific to the appropriate view, field, or procedure. Developer Help, if available, is shown after User Help.
   c. The status of "Show Help" button for each screen will be saved for each user across logins and navigation.
4. For AI based help, the main menu will also contain an item labeled 'Help'. Selecting "Help" will show a screen with 2 components; an input search textfield and a multiline response textview. When the user types in the input textfield, LSMB will search for related help using various AI, NLP, LMM technologies and show what it finds in the multiline results textview. If Developer Help is installed this response will include it.

Design

Contextual User or Developer Help

Screen based contextual help will be available via an icon or multiple icons on a screen. When the user click on the icon the help will be loaded from the database and shown in a pop-up. If the database help text contains image links, they will also be loaded.

The screen based help will be developed either specifically for the help system or moved from the book, and stored in the database help table. For an example help table, see below.

Where screen fields directly match database fields, the help can be loaded from the database column comments. If necessary, the database column comments can contain both user and developer comments. The database column comment can be annotated so the appropriate text is used.

Translations will be exported from the database, updated, then imported back into the database.

User help will be available for both login.pl and setup.pl

While some help may need to be loaded into the help table via a configuration file, it is anticipated that a view will, if necessary, add or update its own help in help table when it is initialized. That way help can updated when any changes are made to the view simply by including the new help in the view code.

Now one might wonder why use the help table at all? Good question. The answer is that the help table is needed for the ChatGPT like search functionality.

In my own code I am not yet using a LLM, so I maintain vectorized search strings separate from vectorized response text. Some more research or someone more knowledgable is needed here. If that is needed then the help table example below will change.

AI Developer Help

Developer help will make available all text that is in perl files (perldoc), database comments, etc. via a ChatGPT like (question & answer) interface. Essentially any text that can be scanned in the code base.

The only difference between User help and Developer help is the depth of content.

All developer help will come from scanning developer generated files. No manual help writing will be used. As such, it is not expected to significantly increase the LSMB download size.

Technical Requirements

With any enhancement there is the need to evaluate added dependencies. The following dependencies are envisioned.

Screen based help may need the following:

1. Text::Markdown - Certainly HTML or LaTeX help could be used, but most non-UI developers are more comfortable with Markdown.

Searchable based help may need the following:

1. PostgreSQL pgvector extension. For storing and searching sentence embedding vectors.
2. Lingua::*. For processing and creating sentence vectors?
3. Text::Sentence. For processing and creating sentence vectors?
4. Algorithm::NaiveBayes. For processing and creating sentence vectors?

Questions

1. Is there a need to keep the book?
   • Does publishing a book in 2024 have any marketing value?
   • Probably for the tutorial.
2. In the new UI can each field have a pop-up?
3. Will pop-ups be enhanced by showing images (screen views)?
4. Is there a need to scan Vue files for Developer documentation?
5. One thing the book is good at is the tutorial. Two options exist.
   • Leave the tutorial in the book. Probably the best short term solution.
   • Move the tutorial to a guided tutorial in LSMB. The better long term solution, but poses some technical problems, including developer resources.
6. What primary format should the help text be in the database? Some options:
   • Template format using Template::Toolkit for the conversion. Which while already used in LSMB is complicated and not straightforward for most developers.
   • Markdown format using Text::Markdown for the conversion. Which makes the source easier to understand.
   • Plain text. Easiest of all, but does not allow easy inclusion of images or text enhancements that aid in understanding.
   • HTML. Yuk, enough said.
7. Is there any unification that should be considered with the existing localization code?
8. Should the help key be an integer as shown below in the example help table with no meaning, should it be a string, with maybe a column for 'View Name' and a column for 'Field Name', or should it be something else.
9. Should the screen help be limited to pop-ups or should there also be the possibility of navigating away from the screen to full window help.

Consequences

1. The book will go away?
2. The release process will be more complicated, but most of the complications will be automated.
3. Comments will have to be added to and maintained for every table, column, trigger, etc. in the database.

Step to implementation

1. Make sure all SQL entities have comments.
   • tables have comments. Can be on-going.
   • table columns have comments. Can be on-going.
   • SQL functions have comments. Can be on-going.
   • SQL triggers have comments. Can be on-going.
2. Make sure all perl functions have correct perldoc. Can be on-going.
3. Create and release the help table and its update procedures. Does not need to be fully populated, but should be populated for one view that is using the new UI. Just get the initial infrastructure in place and released.
4. Then migrate more views as time permits.
5. Add code to scan and update the help table.
6. Start moving more external content to LSMB.
   • Incorporate FAQs.
   • Incorporate book into into the appropriate source.
   • Incorporate other web information.

Technical Notes

The following is only provided to enhance understanding of this proposal.

CREATE TABLE help
(
    help_id         integer   NOT NULL   GENERATED BY DEFAULT AS IDENTITY,
    "language"      text      NOT NULL   DEFAULT 'en-US',  -- IETF BCP 47 language tag
       
    help_format     text      NOT NULL,  -- text, markdown, html, template, etc.
    help_content    text      NOT NULL,  -- actual help content, needs to be translated
    context_labels  text[],              -- assists plain text search, needs to be translated

    help_vector     vector(512),         -- sentence embedding vector (pg_vector) for matching,
                                         -- needs recalculating
                                         -- after every change or translation
    
    source_program  text,                -- automated help creation program name
    source_key      text,                -- source key used to match source auto updates

    notes_to_tr     text,                -- notes to translators
    notes_from_tr   text,                -- notes from translators
    
    create_ts       timestamptz      NOT NULL DEFAULT transaction_timestamp(),
    update_ts       timestamptz      NOT NULL DEFAULT transaction_timestamp(),
    
    PRIMARY KEY (help_id, "language"),
    UNIQUE (source_program, source_key)
);

[neilt]

I've been researching using Perl for calculating sentence embedding vectors, but have not found anything that seems promising.

It looks like we might have to calculate the sentence embedding vectors outside of LSMB using Python. I know, yuck. The general process is described here.

If anyone knowns of any perl alternatives, please add them to the discussion.

[neilt]

Updated proposal to add "Show Help" button and list its benefits.

[freelock]

Hi,

Great proposal!

I don't feel I have much comment on the AI part of this, but for the UX, as well as overall documentation, lots of comments.

First off, I like the "4 types of documentation" framework for documentation - https://docs.divio.com/documentation-system/, https://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/ , summarized as:

• Tutorials
• How-To guides
• Explanations
• Reference

... I think we should consider that the full scope of any documentation efforts -- and clarify where/how we address each of these needs.

I would propose that this proposal is mostly the last one, "Reference", but that we should work as much "Explanations" in as we can. The first two, Tutorials and How-To guides, I would think make sense to put in the website or a standalone book, not necessarily in the app.

UX proposal enhancements

As far as the actual UX is concerned, I like the notion of having a toggle to show/hide the contextual help icons -- maybe put this as a top level menu item, so you don't have to go to a preferences screen? And then I do think there should be two different systems in place for the actual help:

1. Help icons next to each field, to show contextual help in a tooltip dialog (I don't like toasts for documentation, those should be notifications for actions that happen on the server, or possibly actions taken by other users? Not documentation).
2. A "Help Pane" for the entire screen -- I've built these into apps as a pane that slides out on the right side. This page explains the purpose and how you use a particular screen -- and if you open it, it stays open until you close it, changing its contents as you navigate through the app to always show explanations for the screen you're on.

This reminds me of other things we've built, which might help for tutorials/how-tos -- an interactive tour. We've built these using a "Joyride" library, which allows you to specify a sequence of steps, with text in balloons (tooltip dialogs) anchored to the field or button for the current step. Users can either do the action or click "next" in the dialog to move to the next step in the tour.

So that's what I would want to see for in-app documentation. I haven't thought through how AI might work with this system, but I have done implementations of most of the pieces I've described, and have a clear idea in my head about what the interface looks like, and how people interact with it.

Implementation notes

Implementation-wise, I would think we'd have 3 different sources for these 3 different systems:

• Extended help for the field dialogs should be stored near where the fields are defined, I would think -- at least the source language text, and then can use standard tools for generating .pot files to go with it. I would not expect this content to support images, but I would allow a limited set of HTML (for links, emphasis, etc). Each field would have exactly one of these.
• A help table somewhere (database or config file) for the Help Pane text. This would key off the current SPA route, and be responsive -- so as the URL changes, the SPA loads the corresponding help page into the help pane (if it's open). This content should support images and video, I would think...
• A "tour" configuration -- in the implementation we did, we created a Yaml structure for each step, with a CSS selector, URL/route, dialog content, and we might want to add default sample content to fill the form field if the user doesn't enter anything. Tours can span multiple pages, so the main thing we'd need is a way for the front end to load the entire tour, and a button somewhere to trigger it.

Answers to Questions (above)

So my answers to your earlier questions:

1. Is there a need to keep the book?
   Does publishing a book in 2024 have any marketing value?
   Probably for the tutorial.

I don't think so -- I think in addition to what I outlined, developer docs generated from the code seems worthwhile, as a developer docs site -- but I think most of what's currently in the book (at least the last time I looked at it) is better put in the app...

2. In the new UI can each field have a pop-up?

Yes, this is pretty simple with Quasar -- and, I was just hearing that browsers are adding a element as native HTML, which might mean no framework needed for this at all...

3. Will pop-ups be enhanced by showing images (screen views)?

I would say no for field-level help, but yes for page/screen-level help.

4. Is there a need to scan Vue files for Developer documentation?

For a developer documentation site, this is probably a good idea. I don't think we need that for user documentation.

5. One thing the book is good at is the tutorial. Two options exist.
   Leave the tutorial in the book. Probably the best short term solution.
   Move the tutorial to a guided tutorial in LSMB. The better long term solution, but poses some technical problems, including developer resources.

A joyride-based tour, once we hook it up, is really pretty easy to create content for -- the solution we created (in Drupal) allowed non-developers to create them -- the main technical thing they needed help with is identifying the CSS selector for the element to highlight.

6. What primary format should the help text be in the database? Some options:
   Template format using Template::Toolkit for the conversion. Which while already used in LSMB is complicated and not straightforward for most developers.
   Markdown format using Text::Markdown for the conversion. Which makes the source easier to understand.
   Plain text. Easiest of all, but does not allow easy inclusion of images or text enhancements that aid in understanding.
   HTML. Yuk, enough said.

I like Markdown, if we want to avoid having a rich text editor (if we're trying to get more contributions) -- I'd be in favor of Markdown for our doc standard, could be persuaded for other options.

7. Is there any unification that should be considered with the existing localization code?

I would tend to think the field-level help should use the existing localization processes. Not really sure about the rest.

8. Should the help key be an integer as shown below in the example help table with no meaning, should it be a string, with maybe a column for 'View Name' and a column for 'Field Name', or should it be something else.

I would tend to think each field should have a "source of truth" in the code -- where do we define labels for our current fields? The field help text should be right there.

Fine if there's a build step that collects all these to put in the database. No opinion (yet) on the specifics of a database schema.

For page-level help and tours, I'm thinking we should handle those like we handle templates -- have a place where admins can load a specific set into the database, and customize/edit as they see fit. And they can choose to reload any from an update, or not -- allow them to customize their own help content as they see fit...

9. Should the screen help be limited to pop-ups or should there also be the possibility of navigating away from the screen to full window help.

I think that is a bit of a different discussion -- I'm thinking of a company dashboard page, or landing page where a company can manage custom content. We could maybe have a "help" landing page to link out to the website, Matrix, Github, etc, and describe the help available...

Would that be a good place to have AI tips? Maybe a list of your previous queries, sample prompts to get the best results? I see that is what you suggested already -- I think it might be nice to have a few "Getting Started" how-tos, and other explanatory concepts somewhere, but I would think this content could be built on the website first (and possibly loaded into the app through an API call or something, rather than delivered in the codebase).