urbit / operators.urbit.org

operators-urbit-org.vercel.app
3 stars 12 forks source link

update `|bump` documentation - no longer has optional args #88

Open tinnus-napbus opened 1 year ago

forfel-norfel commented 1 year ago

The part about |bump on this page is misleading. https://operators.urbit.org/guides/troubleshooting-basics

It implies that the apps will be suspended and the update will be applied, but I had to hunt around and end up on this page to discover that I actually need to run |bump, =force & to do that. https://operators.urbit.org/manual/os/updates

tinnus-napbus commented 1 year ago

the current version of bump has no force option. If yours does, it's because you're behind a ways on kernel updates

forfel-norfel commented 1 year ago

I figured that out after I made the comment but forgot to follow up. The main issue then is that there's no information about when the documentation was updated and what versions it applies to.

Ideally each page would have versions that correspond to the different releases. It's an effortless system if the docs are already kept up to date because you're essentially just offering an archive of old versions, but I know that's probably not the case here, especially with two separate software components.

An alternative to that would be to offer the old and new information on the same page with the details for the old version collapsed.

If that's still too much work, mentioning the version when something was introduced or changed would still be very helpful.

You can argue that people shouldn't be running old versions, but the reason I was reading the documentation in the first place was because I needed to troubleshoot a ship that wouldn't update.

sethfork commented 1 year ago

The docs have been outdated on this for a while & in multiple places. There's no user-facing place, nor search-engine friendly solution for sanity-checking or realizing the following error could be the result of a change; I'm including it in hopes it will get indexed for anyone searching:

> |bump, =force &
[%keyword-arg-failure {%force}]
-tack.force
-find.force
dojo: generator failure