"pc-updatemanager" not found in the user guide

[grahamperrin]

Reading https://discourse.trueos.org/t/cant-boot-after-upgrade/404/8?u=grahamperrin reignited my curiosity about the effects of force.

https://www.trueos.org/handbook/search.html?q=%22pc-updatemanager%22 and https://www.trueos.org/handbook/search.html?q=pc-updatemanager find:

• advertisements only
• nothing relevant; I searched repeatedly.

[q5sys]

I'm not the one to make the final decision on this, but I don't think it is a good idea to fill the User Guide with a myriad of CLI tools. Users 'should' update their systems the way that is described in the handbook: https://www.trueos.org/handbook/sysadmclient.html#update-manager

There is an argument to be made that all TrueOS CLI tools should have a man page written up about them, but I do not feel we should be filling up the user guide with that information.

[grahamperrin]

Not filling up. pc-updatemanager is probably at, or near, the core of the majority of puzzles and confusions that arise in the community around update times. I reckon that there's a good case for it to have at least a mention in the guide.

[q5sys]

The core of the issue surrounding what gets included in the user guide is the matter of degree. The point of the user guide is to have an easily accessible source of information, that will cover the majority of problems a new user will face when trying to learn the system. For new users, I would never recommend updating at the command line. That should come after they are comfortable with their system and are willing to dig a little deeper. At this point, a man page would be sufficient.

So we reach the issue of degree... how much information can be in the user handbook before it becomes so colossal that it's size becomes a detriment. The simple fact is that people will shy away from resources with massive amounts of information because they feel that the likelihood of them finding the information they need is small due to the vast amount of information available.

As for what to include, here the issue of degree also arises. Some may feel that pc-updatemanager is a good idea to include. Others no doubt would argue that beadm should be included. Some would argue that zpool should be as well. It's a very slippery road to go down because a valid argument can be made for their inclusion. However the moment you start making those decisions you intrinsically validate the argument to include other CLI tools, and before long the User Guide is filled with CLI tool documentation.

Maybe I'm an old greybeard in that I feel that CLI tools should come with CLI documentation and GUI tools should have GUI documentation. Mixing the two is a recipe for making each one less useful.

[grahamperrin]

CLI tools should come with CLI documentation

+1 e.g. https://gitter.im/trueos/Lobby?at=584da4329750c95b4f8a8371 with steering from Joe to upstream.

zpool(8) is very well documented beyond the TrueOS domain with no need for repetition here.

The manual page for beadm(1) could be better but with https://github.com/trueos/trueos-core/issues/162#issuecomment-261809173 in mind I have enhancement requests on a back burner.

[Mrt134]

I agree CLI elements need documentation, but q5sys is also right - the TrueOS handbook is already very large (and constantly growing) and is in real danger of losing focus from its original purpose to introduce/help a completely new user install TrueOS. We'll discuss it internally with Dru and others and see what they recommend.

As an aside, we've been upgrading and testing the search algorithms for Sphinx documentation using the TrueOS handbook as a test platform. When it works, it is miles better than what existed before, and saves the documentation writers a ton of time, but we're still in the process of ironing out the bugs, so please bear with us if the search menu isn't working properly.

[Mrt134]

Update: CLI documentation was split from the TrueOS handbook when SysAdm was created. The SysAdm API reference guide (api.sysadm.us) is the recommended method for new users to interact with pc-updatemanager and other TrueOS utilities. However, after conversing with Ken, pc-updatemanager is something of a special case requiring additional documentation. We are in the process of writing manpages for pc-updatemanager and other TrueOS command line utilities. These pages (when ready) will be referenced in their respective utilities' handbooks and subsections, but will not be fully reproduced in the handbooks.