Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
Problem/Motivation
Following up from this "Inline user guides" forum topic: https://farmos.discourse.group/t/inline-user-guides/680
I'd like to propose we leverage the Drupal core help and help_topics modules for providing this kind of self-hosted inline user guide for farmOS.
Some core documentation on help topics: https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or...
Features of this approach:
helpmodule provides an existing "HelpSection" plugin + UIhelp_topicsmodule provides a frame work for providing individual help topics plugins via twig files or php classes- Version controlled
- Self hosted docs
- Translated via localize.drupal.org
- Contrib modules can provide docs
- Individual help topics can be considered "top-level" to display within the Help section
- Help topics can specify "related topics" whose links are included below (bi-directional relationship, related topics are displayed on both pages)
- Help topic twig files could (in theory) be parsed and pulled into farmOS.org docs, potentially pull translations from localize.drupal.org
I've attached a screenshot of what the /admin/help page looks like with the help_topics module enabled. The core help module is what enables this page itself as well as the "Module overview" section on the bottom. The help_topics module provides the "Topics" section and is designed to be a layer above the simple "module overview", similar (as I understand) to our farmOS user guide. These help topics can be provided by any module, and only the "top-level" topics are displayed within this "Topics" section. Individual topics can also specify "related topics" that are rendered (bi-directionally) as links at the bottom of a topic page.
Without any custom code farmOS could simply add some top-level topics that would be displayed in this "Topics" section. But it would be ideal if farmOS topics could have their own section, since only site admins need to see these other Drupal topics. In my investigation I found it's simple to create additional sections - in the screenshot I included an additional "Farm topics" section. This is where dedicated farmOS help topics could be displayed!
The missing link is trying to leverage the existing help_topics framework, but put them in our own dedicated section. I actually chatted with @jhodgdon in the Spokane drupal meetup for ideas on this. We might be able to extend the help_topics HelpSection plugin itself and/or implement some alter hooks to change which help topics end up being displayed in the farmOS section. OR it might be easier to go a step further and extend the help topics plugin + discovery to check for help topics in a dedicated farm_help_topics directory. This way we'd have more control with our own plugin, but be inheriting the core help_topics features. ***errr this might break translations on localize.drupal.org though.
Also notable is this "config help" sandbox project from @jhodgdon (might not be working at the moment): https://www.drupal.org/sandbox/jhodgdon/2369943 Originally the help_topics module was going to use config entities, but they decided against it because config entities are not forced to say in-sync with the source code (site admins would have to update the config after changes). Makes sense, and inline with our desire for version controlled docs! But help topics as config is generally interesting as well - a farm manager could create dedicated help topics for tasks on the farm that workers could reference... :-)
Steps to reproduce
N/A
Proposed resolution
- Extend & reuse the
help_topicsplugin manager to load "Farm help topics" from a dedicatedfarm_help_topicsdirectory within each module. - Create a new "farmOS Topics" help topic section (see screenshot for simple example). Display all top-level "Farm help topics" inside this section.
Remaining tasks
Decide on an approach. Figure out if translations would work in our own directory. Implement! And provide docs :-)
User interface changes
Inline user guides/module documentation available from the farmOS UI. At /admin/help and/or dedicated menu/toolbar items?
API changes
New "farm help topics" plugin.
Data model changes
None.
| Comment | File | Size | Author |
|---|---|---|---|
| help_topic_example.png | 197.63 KB | paul121 | |
| farm_help_topics.png | 230.79 KB | paul121 |
Comments
Comment #2
paul121 CreditAttribution: paul121 commentedAlso on the topic of "styling" these help topics pages.. they are admittedly pretty simple! Certainly not comparable to the current farmOS user guide site. But I do see that these pages are using the "help_topic" theme hook and template, so I imagine the farmOS help topic template could be customized a bit more.
I also imagine modules could include images, gifs, etc that could be referenced in these help topic twig files but perhaps that is a more general thing to take into account with the revamped farmOS.org user guide - would it take such image assets from the module source?
Comment #3
m.stentaI like this idea a lot! In theory at least...
Whether or not it's a good fit might ultimately depend on the content we're trying to fit into it (and where else we are trying to use that content, like on farmOS.org). If we're specifically talking about the User Guide, I think our first step should be to pull the existing guide markdown files into the 2.x branch under
/docs, update them, refresh on what we're working with, and then decide next steps.We've also been discussing aggregating user guide markdown files into the new farmOS.org via Gatsby.js - so if they are in Twig files instead of Markdown we'd have to figure out how to make that work too.
Alternatively, maybe it will make sense to keep the "User guide" somewhat separate, but ALSO build out some more inline documentation using help topics.
We'll have to think about all this pretty soon - I'd like to get the user guide together (a first pass at least) soon after the first beta release. So let's come back to these ideas soon! :-)
Comment #4
m.stentaI would also prefer to avoid using the default
/admin/helppage if we can, and instead provide our own at/helplike we do in 1.x, to avoid having all the additional Drupal-admin stuff in there. Our help section should be targeted at farmOS users only - not Drupal site builders. :-)Comment #5
paul121 CreditAttribution: paul121 commentedRevisiting this again...
This has been done! farmOS.org now pulls documentation, including the user guide, from `/docs` at `farmos/farmos`. Regarding if the user guide is a "good fit" here: I've just taken a pass at our current user guide and, yes, I'm optimistic! What I see that every menu item in the user guide is either isolated to an individual module or is a top-level category for things that multiple modules provide:
This jibes well with the structure of help topics: some can be "top level" with other more detailed topics (like help about an individual asset type) referencing the top level topics. The difference for help topics is that each "top-level" page (like Managing assets) would not include the description of each asset type, instead it would only include a link to the related asset type help topics.
BUT that's all "out of the box" - we do have the ability to customize how these help topics are displayed! I imagine that the "top-level entity type" topics could indeed render a snippet of each bundle type's individual help topic with some custom code.
This sounds the best IMO. Trying to automate farmOS.org to be in sync with some kind of "inline user guide" just seems like it adds too much initial complexity right now. There is some real value to be had in an "inline user guide" implemented with help topics right now!
A client project recently requested some related work: (see screenshot here) https://github.com/paul121/farm_regen_digital/issues/1. I've overwritten the standard "Help" menu link to go to a custom help page. This page uses the existing help section theme & module help pages to render links to the relevant help information provided by select farmOS contrib modules. This isn't actually using help topics at all but considering that module help pages are on path to be replaced by help topics, it basically is!
I modeled the help page here after the core "Getting started" steps at `/admin/help` and some language from our existing user guide. What's really cool about this is that we have the ability to create an "interactive inline user guide" with links to "actions" the user should take! These steps could even be shown/hidden a bit dynamically based on the "state" of the farmOS instance (new vs old, etc). On top of this everything can be translated. These features we can't have on farmOS.org but would be really great to start working on & supporting now!
Comment #6
m.stenta