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.
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.
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.
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 repo), and then somehow just automatically parse those into the Drupal route so they appear within the /guide section.
@paul mentioned another interesting idea in the farmOS Redesign topic:
Drupal 9 has a core concept of Help Topics. 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 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…
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”.
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.
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 - but within a single farmOS instance there is value in only showing (detailed) docs for the relevant/installed modules
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
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).
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 into the mix adds complexity and will prevent us from making progress here.
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 (which i have doubtless plugged elsewhere in these forums before, but it bears repeating, in case you missed it )
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!
I do like the 
)