Maslow Home Maslow Community Garden Newsletter

Help System - Online vs. Offline

Currently WebControl supports both online and offline help. When the user clicks Help->Online Help, it brings up a new tab that takes the user to a website that hosts the help webpages. When the user clicks Help->Offline Help, it brings up a modal window (window that overlays the screen) that displays the help webpages. To make this work, a single set of help pages has been created. The online help webserver references these pages off the github repository where all the files/source code to WebControl is stored. The offline help “includes” the pages in the release files. This way, we don’t have to maintain two sets of documentation files.

With that said, we are looking at ways to add more content and edit existing content, in a collaborative manner. The problem right now is that the current system of using one set of files is a cumbersome and requires that things be done in a precise manner and the only way to know you got it right, is to do a bunch of testing. I spent more time fixing formatting issues between offline and online help than I did doing actual documentation.

What I would like to propose (and get feedback on) is to bifurcate the help system by using a separate set of files, leaving offline help being basic instructions that don’t change often and online help being more “expanded” help. This would allow us to do more collaborative work on the online help system and people don’t have to be developers or markdown experts to create it. We could also add links in the offline help files that point to the online help pages where users can obtain more info on a topic.

1 Like

This sounds very reasonable. The web hosted documentation can be more complete with the version in the software more minimalistic for basic functionality.

Having two sets of help files is going to get tiresome fast. Plus, there’s no guarantee that the Maslow controller is going to be online all the time. There’s nothing worse than clicking on a help button and getting a blank page because the network is down or because the other end isn’t there any more.

Presumably you want people to update their installation by using git tools? It doesn’t actually matter how it’s done, but I think the help files should be downloaded as part of the package and available locally. If the user wants the latest help files they can update the package. The update may or may not include new software, and may or may not include new documentation. However, the combination of software and help in any particular package should be consistent. In fact, there’s no point having new updated online help that refers to features not available on an older local version of the software.

At least, that’s my opinion.

Local help files please. I assume there are others like me who don’t have WiFi in their shop/shed/garage. I have no problem googling a problem but if i click help in the menu of an application I expect it to give me information regardless of my network connection.

3 Likes

The idea was to still have offline help… just that it’s more static content. How to do things, basic troubleshooting. The online help would have that, but more documentation. possibly explaining the theory behind things and perhaps generalized Maslow instructions as well. For an extreme example, lets say there’s a video of how to calibrate… there’s no way we are going to embed video files into a release so that they can be viewed offline, so that would only be available online only.

User would update their installation via the built-in update function. No need to use git.

I’m not advocating for maintaining previous releases… we aren’t developing an operating system or something where we need LTS versions. I have added a tag to the files to let the user know the ‘minimum’ version the document/feature refers to, but expect the user to upgrade regularly. It’s painless to do.

That’s still proposed, just that it be an abridged version that doesn’t change much.

2 Likes

I understand now and am all for it. I like the idea of the video help and understand how that’s impractical to include in the help file. As long as there is a local help file explaining functions of the software everything else to me is just gravy.

1 Like

Hello, I can’t understand one thing, but can webcontrol work only on raspberry?
Thanks.

Works on Windows and Linux as well… and I think MacOS with the new build process.

1 Like