Plan UI usability (adding expedition.yaml guidance)
#277
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Collaborator
|
Great that you managed this. It was mentioned by several OSL students in the interviews. |
ammedd
reviewed
Feb 4, 2026
| "The next step is to finalise the expedition schedule plan, including setting times and instrument selection choices for each waypoint, as well as configuring the ship (including any underway measurement instruments). \n", | ||
| "\n", | ||
| "<div class=\"alert alert-block alert-info\"> \n", | ||
| "**NOTE**: This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. This is the recommended way for most users but when expeditions become larger with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the** `expedition.yaml` **file directly (see [here](../tutorials/working_with_expedition_yaml.md) for more details on how to do so)**.\n", |
Collaborator
There was a problem hiding this comment.
Change: This is the recommended way for most users but when expeditions become larger
to For expeditions
|
|
||
| The `expedition.yaml` file is ingested by `virtualship run` and is used to configure expeditions. It contains metadata and settings that define the parameters of an expedition, including information about ship speed, instrument configurations, waypoint timings and instrument selections. | ||
|
|
||
| This tutorial describes an alternative means to using the `virtualship plan` command, which provides a user-friendly interface for interacting with `expedition.yaml` but can become cumbersome for long, complex expeditions with many waypoints and instruments. Interacting with the `expedition.yaml` file directly tends to be faster for larger expeditions. |
Collaborator
There was a problem hiding this comment.
add: and experienced users.
|
|
||
| This section contains a list of `waypoints` that define the expedition's route. Each waypoint includes: | ||
|
|
||
| - **Instruments (`instrument`)**: A list of instruments to be deployed at that waypoint. Add or remove instruments by adding or deleting entries on _new lines_. |
Collaborator
There was a problem hiding this comment.
Be explicit if a waypoint always needs an instrument
Collaborator
Author
|
Thanks @ammedd, I've incorporated your suggested edits 👍 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Previous courses have identified that the
virtualship planUI can become cumbersome to use when an expedition has many waypoints (#267).I have now looked into this and see that when running locally, having many (e.g. > 30) waypoints does introduce a small lag to the application but it is still usable. However, doing the same in a remote SURF environment results in substantial lag, confirming what was observed in-class. I can do more investigation on this but in the near-term I don't think there's a quick fix, unfortunately.
Therefore, as suggested in #258, this PR adds an additional doc to the tutorials providing guidance on the structure of the
expedition.yamlfile and how to edit it. There are now also references to this tutorial in the quickstart guide, the sail_the_ship assignment and the YAML itself, encouraging users to interact directly with the YAML file if their expeditions are large.Also includes some small tweaks to the tutorials section layout (and thumbnails) in the docs.
Closes #267