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.
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.
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.
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.
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.