# Inline user guides **URL:** \ **Category:** Development\ **Created:** [February 27, 2021, 6:55pm UTC](https://farmos.discourse.group/t/inline-user-guides/680 "2021-02-27T18:55:28Z")\ **Posts on this page:** 11\ **Page:** 1
**Author:** ![mstenta](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/mstenta/32/4_2.png) [@mstenta](https://farmos.discourse.group/u/mstenta)\ **Post date:** [February 27, 2021, 6:55pm UTC](https://farmos.discourse.group/t/inline-user-guides/680/1 "2021-02-27T18:55:28Z")
Spinning off this as a separate topic from [farmOS.org Redesign](https://farmos.discourse.group/t/farmos-org-redesign/505), where @Symbioquine wrote: > I still favor the strategy of making the user guide portion of the documentation self-hosted. i.e. Making it part of farmOS itself… If we do that as part of a final 7.x-1.x release, that documentation could live as long as there are any 7.x-1.x installations online. > > Another advantage of self-hosted documentation is that it works in offline/air-gapped/limited-connectivity scenarios. I’m imagining a farm/homestead which has off-grid power and a sketchy internet connection but runs farmOS on a local network. > > Obviously the current version of the user guide should also be available online at [farmOS.org](http://farmOS.org). > > GitLab does an excellent job of this sort of thing. If you host a local instance all the “help” links and stuff reference self-hosted copies of the documentation - which besides working “offline” also is nice because you can tell you’re looking at the documentation for the version you’re actually running. ---
**Author:** ![mstenta](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/mstenta/32/4_2.png) [@mstenta](https://farmos.discourse.group/u/mstenta)\ **Post date:** [February 27, 2021, 7:06pm UTC](https://farmos.discourse.group/t/inline-user-guides/680/2 "2021-02-27T19:06:00Z")
I love this idea! A few days ago I started a `2.x-guide` branch in my fork of farmOS: [Comparing 2.x...2.x-guide · mstenta/farmOS · GitHub](https://github.com/mstenta/farmOS/compare/2.x...mstenta:2.x-guide) It doesn’t do much right now just adds `farm_ui_guide` module, which provides an empty `/guide` route, with a nice little icon/link in the top right. 🙂 ![Screenshot from 2021-02-27 14-02-53](https://global.discourse-cdn.com/free1/uploads/farm_os/original/1X/3ea1d6eccacb1ef51decb0eacae940af4d4152eb.png) I’ve been working on the 2.x `/docs`, and my thought was "perhaps we can add `/docs/guide` as Markdown files (copied/updated from the [farmOS.org](http://farmOS.org) repo), and then somehow just automatically parse those into the Drupal route so they appear within the `/guide` section. I found this, and was curious if it would handle the “parsing” piece: [markdown\_to\_html - Documentation - Twig - The flexible, fast, and secure PHP template engine](https://twig.symfony.com/doc/2.x/filters/markdown_to_html.html) ---
**Author:** ![mstenta](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/mstenta/32/4_2.png) [@mstenta](https://farmos.discourse.group/u/mstenta)\ **Post date:** [February 27, 2021, 7:40pm UTC](https://farmos.discourse.group/t/inline-user-guides/680/3 "2021-02-27T19:40:02Z")
@paul mentioned another interesting idea in the [farmOS Redesign](https://farmos.discourse.group/t/farmos-org-redesign/505) topic: > Drupal 9 has a core concept of [Help Topics](https://www.drupal.org/docs/develop/documenting-your-project/help-topic-standards). It’s an experimental module right now - but will soon be stable! These are fairly targeted towards general Drupal administration, but I think it would be possible to create dedicated sections for farmOS topics and “hide” what isn’t needed for normal users. They should be theme-able as well. > > A nice feature is that they can be translated with the existing Drupal localization service. But perhaps a downside of this is the topics need to be written in twig files. Markdown would probably be best… but maybe a script could auto-generate the twig files from markdown?? The translation potential is very appealing! And perhaps the [Twig filter](https://twig.symfony.com/doc/2.x/filters/markdown_to_html.html) I linked to above could help? I’m curious to understand how the files need to be structured. It sounds like you put “help topics” in each module that is responsible for them. But our current user guide content might not fit that model exactly. So that would be something to think about… ---
**Author:** ![mstenta](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/mstenta/32/4_2.png) [@mstenta](https://farmos.discourse.group/u/mstenta)\ **Post date:** [February 27, 2021, 7:43pm UTC](https://farmos.discourse.group/t/inline-user-guides/680/4 "2021-02-27T19:43:11Z")
> If we do that as part of a final 7.x-1.x release, that documentation could live as long as there are any 7.x-1.x installations online. I like this idea @Symbioquine - but honestly I’m not sure it’s worth the effort for 1.x. If we’re going to put any work into this, we should focus on 2.x, and consider 1.x docs “legacy”. Something I said in the [farmOS.org Redesign](https://farmos.discourse.group/t/farmos-org-redesign/505) topic: > So that’s also part of my reasoning behind splitting 1.x out to [https://1x.farmOS.org](https://1x.farmOS.org) entirely. If we plan for that future, then we can just “retire” the old [farmOS.org](http://farmOS.org) repository altogether! Perhaps even move it to [GitHub - farmOS-legacy/farmOS.org: This is the code that runs the official v1.farmOS.org website.](https://github.com/farmOS-legacy/farmOS.org) as part of the first pass… ---
**Author:** ![Symbioquine](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/symbioquine/32/284_2.png) [@Symbioquine](https://farmos.discourse.group/u/Symbioquine)\ **Post date:** [February 27, 2021, 7:49pm UTC](https://farmos.discourse.group/t/inline-user-guides/680/5 "2021-02-27T19:49:02Z")
> [@mstenta](#): > > I like this idea @Symbioquine - but honestly I’m not sure it’s worth the effort for 1.x. If we’re going to put any work into this, we should focus on 2.x, and consider 1.x docs “legacy”. Seems reasonable. I wasn’t super attached to this, just trying to propose a solution to the problem of keeping the docs accessible while folks are still using 1.x. ---
**Author:** ![mstenta](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/mstenta/32/4_2.png) [@mstenta](https://farmos.discourse.group/u/mstenta)\ **Post date:** [February 27, 2021, 8:01pm UTC](https://farmos.discourse.group/t/inline-user-guides/680/6 "2021-02-27T20:01:14Z")
👍 Yea, I think we can just point folks to the legacy docs. I’m really excited to see how we can do this in 2.x though! ---
**Author:** ![paul121](https://avatars.discourse-cdn.com/v4/letter/p/54ee81/32.png) [@paul121](https://farmos.discourse.group/u/paul121)\ **Post date:** [February 27, 2021, 9:41pm UTC](https://farmos.discourse.group/t/inline-user-guides/680/7 "2021-02-27T21:41:03Z")
> [@mstenta](#): > > It sounds like you put “help topics” in each module that is responsible for them. But our current user guide content might not fit that model exactly. So that would be something to think about… Yes this would need some thought. And TBH I’m not super familiar with the user guide so I should become more familiar with it… 😄 I do like the `User guide` link in the toolbar though! One other thought: Help topics would be especially useful for farmOS Contrib modules. Maybe the “core” user guide could link to the help topics for all installed farmOS modules? The more “complex” core modules could provide more detailed documentation via help topics as well (thinks like crop plan, livestock weight report, etc..) There seems to be value in having _all_ the docs on [farmOS.org](http://farmOS.org) - but within a single farmOS instance there is value in only showing (detailed) docs for the relevant/installed modules ---
**Author:** ![paul121](https://avatars.discourse-cdn.com/v4/letter/p/54ee81/32.png) [@paul121](https://farmos.discourse.group/u/paul121)\ **Post date:** [October 15, 2021, 7:31pm UTC](https://farmos.discourse.group/t/inline-user-guides/680/8 "2021-10-15T19:31:21Z")
After doing a bit more investigation (inspired by this issue: ), I think the help\_topics module could be quite useful! I was really impressed with the bi-directional “related topics” feature 🙂 Created a dedicated issue with more info & to consider using it: [Consider leveraging help topics for module documentation [#3243901] | Drupal.org](https://www.drupal.org/project/farm/issues/3243901) ---
**Author:** ![mstenta](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/mstenta/32/4_2.png) [@mstenta](https://farmos.discourse.group/u/mstenta)\ **Post date:** [October 18, 2021, 1:39pm UTC](https://farmos.discourse.group/t/inline-user-guides/680/9 "2021-10-18T13:39:03Z")
Cool! Thanks for looking into that @paul121! So maybe the next step would be to look through our existing User Guide and figure out if/where each bit would fit into a module in 2.x. We may face some challenges with those decisions, as the guide tends to be “above” the lower-level module distinctions (at least that’s my sense - but we need to look). ---
**Author:** ![paul121](https://avatars.discourse-cdn.com/v4/letter/p/54ee81/32.png) [@paul121](https://farmos.discourse.group/u/paul121)\ **Post date:** [April 19, 2022, 12:23am UTC](https://farmos.discourse.group/t/inline-user-guides/680/10 "2022-04-19T00:23:50Z")
I’d like to pickup this conversation again. TL;DR I think inline (interactive!) user guides implemented as help topics could be very valuable & really quite easy to implement in the short term. Trying to bring [farmOS.org](http://farmOS.org) into the mix adds complexity and will prevent us from making progress here. See my thoughts here: [Consider leveraging help topics for module documentation [#3243901] | Drupal.org](https://www.drupal.org/project/farm/issues/3243901#comment-14485302) And a tiny example of what this could look like here: [Help page · Issue #1 · paul121/farm\_regen\_digital · GitHub](https://github.com/paul121/farm_regen_digital/issues/1) ---
**Author:** ![walt](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/walt/32/13_2.png) [@walt](https://farmos.discourse.group/u/walt)\ **Post date:** [April 19, 2022, 3:26pm UTC](https://farmos.discourse.group/t/inline-user-guides/680/11 "2022-04-19T15:26:22Z")
Am not sure i understand the scope & form of proposed implementation, but taking the TL;DR at face value, i am +1 on the idea of “inline (interactive!) user guides,” for sure! In fact, as i am now faced with the challenge of training & supporting new users in our farm context, and am trying therefore to look at this system through new user eyes, it seems to me that- intuitive as the GUI may be- it could certainly benefit from some more obvious help affordances (indeed: unless you have (instance)/admin/ menu access and are interested to see docs for specific system modules, i’m not seeing any help affordances at all!). So: that idea from @Symbioquine cited by @mstenta at the top of this thread- i.e. “Making it part of farmOS itself” -strikes me as ideal, presuming that makes it very accessible in the GUI, and moreover customisable at the instance level ideally. Is that what we’re talking about here? NB: I don’t actually know what is meant by either User Guides or ‘help\_topics’… But what i am looking for (on behalf of my users) is the sort of problem-oriented “How-To Guides” that are positioned in topRH corner of that 4-square grid that holds the [Grand Unified Theory of Documentation](https://documentation.divio.com/) (which i have doubtless plugged elsewhere in these forums before, but it bears repeating, in case you missed it 😁 )