[Help Editor] : clarify docs / maybe rename to "Instrument Instructions"

[christinerogers]

This module can be used for instrument instructions but not very easily for module help customization, currently. The name Help Editor is not... accurate.

How the Help Editor actually works (per ZR) :

• Instruments : their help text still needs to come from the database table

• Modules: their help text comes from the markdown file

  • Don't/can't use the Help Editor to edit these markdowns.
  • To override this content, their custom Help text has to be loaded from the database table (e.g. in RB schema) * Custom help would need a lot of merging/maintenance

So... how do project admins actually set up custom help for Modules?
e.g. for a new custom module, how would a project admin add help text?:

• Do they need to copy sample raw Markdown file codes (like... find another Help raw .md on GitHub?)
• then... go to the module and edit the help dropdown? (no Edit button anymore)
• then paste the markdown codes in, and then save (no way to do it) it to the database?

todo :

• [ ] rename the Help Editor module?
• [ ] The documentation needs to be updated. Module spec, Help text, test plan
• [ ] Add to Rida's guide in progress: customize your instrument Help text, here's how...
• [ ] How should it work for project admins who want to add custom module text?

[johnsaigle]

@zaliqarosli @ridz1208 Do you think you could clarify some of the above points?

[zaliqarosli]

i commented on the PR that was issued

https://github.com/aces/Loris/pull/5746#issuecomment-560578335

[johnsaigle]

Copying the comment referenced in the above post ⬆️ below. I think it'll be a bit easier to carry on the discussion here.

---

this is how editing help content works:

Modules get 'Help' content from Markdown help file in modules/module_name/help. Instruments and modules without help file get content from DB help table. Only help content from DB is editable on the front-end using the Help Editor module (content for .md files are not editable on the front-end).

This is from the description of PR #3558. This was how the code worked from even before I made changes to the module. This PR #3345 removed the projectContent column of the help table.

Whilst the Markdown help file is favoured over the DB help table, maybe we should reverse this order of preference. If people agree, I can make a github issue for this @driusan @johnsaigle @christinerogers @ridz1208 . I'm also having trouble finding where the code for this is if anyone knows!

[johnsaigle]

Answering questions based on what my understanding is (please let me know if I've misunderstood any part):

So... how do project admins actually set up custom help for Modules? e.g. for a new custom module, how would a project admin add help text?:

I don't think it's possible without back-end access. You would need to either:

1. Create a new markdown file under `projects/modules/$custom_module/help/$custom_module.md, OR
2. Create an entry in the help table.

both of which require back-end access.

A developer could create an entry in the help table which could then be edited by a front-end admin.

then paste the markdown codes in, and then save (no way to do it) it to the database?

As far as I know the module only allows editing existing help text, not creating new help text, so I don't think that this would be possible.

rename the Help Editor module?

I'm in favour of this as core modules should all have relatively up-to-date help files.

How should it work for project admins who want to add custom module text?

I don't think it's possible to add custom module text from scratch the way things are coded. The easiest way at the moment would be for a developer to create a Markdown file which can be tracked in the project repo and modified accordingly. This is in order to add new text.

To edit custom module text, that content would need to be present in the DB... however this means it probably won't be version controlled which isn't ideal.

We could create a feature where users can edit and create new help files but I think we would need to design this as a "secure file upload" type of feature rather than as a "edit DB data" type of feature so that the files can be properly version controlled (and for consistency with other module help text).

[christinerogers]

Hi John, my recollection is that when the Great Markdownization happened, the idea was projects could maintain their custom help/markdown, and as Rida suggested last Tues, this is a reasonable feature to support, though they'll have to deal with the pain of maintenance. You mention, for custom modules --

Create a new markdown file under `projects/modules/$custom_module/help/$custom_module.md,

? Does this actually load, currently ?

[johnsaigle]

I'm not sure. I don't really have any experience with module overrides, though my understanding is that anything under that path should be loaded in place of the default. Maybe a project maintainer could provide more context.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

The Stale label is being removed automatically because some activity has occurred or because the developers have decided that this pull request is important and should not continue to be overlooked.

[adamdaudrich]

ok I am going to tackle this now