Arvados

Branch 20497-updating-wgs-tutorial @ commit 119d8d1502dddf00ba2fc088238299922723cbaa.
The only feedback not addressed from 17846 (https://dev.arvados.org/issues/17846) is I kept the tutorial for the 10 genome all chromosomes since the 5 genome chromosome 19 workflow from Jiayong was private (although I made my own version I could theoretically work through) and I could not rename this workflow: https://dev.arvados.org/issues/17846. Additionally, I just removed the reference to the input FASTAs being editable, since I'm not sure if I am able to actually make them editable.

Alex Coleman wrote in #note-8:

Branch 20497-updating-wgs-tutorial @ commit 119d8d1502dddf00ba2fc088238299922723cbaa.

So let me say up front, there are a bunch of overlapping issues here, and I realize that. Even when it was fresh and well-matched to Workbench 1, the tutorial text had gaps that can make it difficult to follow. And because this ticket doesn't have much description to explain what you are and aren't expected to update, it's hard for me to know what to flag in review vs. not.

Here are issues I noticed that are definitely about the parts of the tutorial that guide users through Workbench, and that I think would be straightforward to resolve. I think they're at least in the spirit of the ticket. If you have other instructions from Peter or whatever that make you feel like a specific comment is out of scope, feel free to say so. I'm filing a separate issue with non-Workbench tutorial issues I noticed.

In general, on my 4K resolution monitor, all the new screenshots of Workbench 2 are in a tight enough space that it's effectively impossible to read any text on them, making it hard to know what they're trying to show me. The text in them is about half the size of the tutorial text, maybe a little less. I would encourage you to try retaking these screenshots in a window that's about ⅓-½ the width. It could also help if the accompanying text gave more direction about what it's showing you, or if important parts were highlighted more consistently.

• Section 3a "Setting up a New Project": In the text before the first screenshot, "New Project" is capitalized but the actual menu entry "New project" is not. It would be best to keep them in sync.

• I think part of updating the guide should include directing people to use new Workbench 2 features where they're available. In the discussion of the project UUID, the tutorial directs people to get that from the URL. However, I think most users would prefer to press the 🛈 button in the upper right for Additional info, and get/copy the UUID from there, especially since we provide a handy copy button. image7.png could help illustrate this too.

• The caption for figure 6 mentions editable fields, but does not give any indication of how to edit them. I think instead of the "(editable)" parenthetical, it would be nice to add a sentence to explain that some of these fields can be edited through the Edit button in the 🛈 Additional info menu.

• The caption for figure 6 mentions the collection's "content address," but Workbench 2 doesn't call it that, so this can be a confusing disconnect. It would be better to update this to say "portable data hash" to match Workbench 2.

• From Section 4 on: the tutorial sometimes uses Bootstrap styling to make it clear when it's talking about a specific button or UI element. With Workbench 1, the styling in the tutorial matched the UI exactly. Now it doesn't, which I think could lead to confusion or worry on the reader's part. Given that we already don't apply the styling consistently, I think I would advocate that we remove it everywhere. (If we want to revisit this, we can make a separate issue to come back and apply it consistently across the tutorial, not just on the elements that currently have it.)

• Section 4a talks about a “Run a Workflow” button that has the same capitalization problem as "New Project" above, in Workbench 2 it's just "Run a workflow".

• Section 4a step 1 tells you to find a workflow by searching for it. This doesn't work in Workbench 2, because the search feature does not support searching workflows. I guess for now we need to navigate to the project, then to the workflow.

• Section 4a step 2 tells you to press the Run workflow button and select a project. Given this text, I was surprised when I pressed the button and was presented with an entire screenful of inputs. I think the text could be restructured to be more specific about what the flow is, and where the reader can select their project. Adding a screenshot here to highlight the input might help, since the project selection input doesn't really jump out compared to all the others on the page.

• Section 4a step 4 says you need to scroll down to the bottom of the page but that's no longer true, the button is always visible at the bottom. The button text is now "Run Workflow" instead of just "Run" so that should be updated.

• Section 5 first option "Via the Dashboard": This option doesn't make sense anymore with Workbench 2. If Workbench 2 has a dashboard, it isn't obvious what it is. There is nothing called "Recent Processes" on the front page. At the very least, this needs to be updated to talk about "All Processes" in the left navigation menu. I think it should also be demoted to being the second option, because finding your workflow via your project is always going to be more reliable, since other users can't affect it.

• Section 5 second option "Via Your Project": This is the first time the tutorial mentions the "Projects pulldown menu" so I don't know what that is. Is it meant to refer to the navigation menu on the left? The note about marking the project as a favorite is also out of date: the star icon that it refers to doesn't exist on Workbench 2. This should be updated to talk about selecting "Add to favorites" from the action menu in a listing.

• In Section 5 after those steps, the paragraph about the name of the workflow doesn't seem to be up-to-date. The way the text talks about "submitted via the Registered Workflow" also feels confusing to me. "Submitted via Workbench" seems clearer and still unambiguous.

• In the first screenshot of Section 6, it would be clearer if the screenshot included all of the process details. The way the screenshot is cropped now makes it look like the output collection link is at the bottom of the Details pane, which is a mismatch with the real UI.

• When section 6 talks about downloading the report, it would be cool to mention first that you can open it directly in your browser just by clicking the file listing. This is sort of like the project UUID thing earlier, where we can improve the tutorial thanks to a better UX in Workbench 2.

• Section 6, "Logs for the main process can be found in the Log tab.": In the previous paragraph, the tutorial was walking us through navigating the output collection. There's no way to get directly to the log collection from that page. A quick prompt to direct the reader to go back to the workflow process page would help prevent confusion. Being explicit about how to open the log collection would also help, because there isn't a link in the Details pane the same way there is for the output collection.

• Section 6, "Now, let’s explore the logs for a step in the workflow.": Like the last comment, the previous paragraph was walking us through a collection, so a prompt to navigate back would be a helpful start. This paragraph and the paragraph that follow feel like they need their whole language and flow updated for Workbench 2. They talk about "workflow steps" where Workbench 2 consistently calls those "Subprocesses." It says "We click the arrow to open up the step, and then can click on the log collection to access the logs," but none of those UI elements exist in the Subprocess listing of Workbench 2. The tutorial talks about the subprocess bwamem-samtools-view2 but it's now called bwamem-samtools-view_2 (note the underscore).

Thanks.

Newest commit @2d453cb79b4e94ed3d559e7874e0d1670daf82da
Brett Smith wrote in #note-12:

Alex Coleman wrote in #note-8:

Branch 20497-updating-wgs-tutorial @ commit 119d8d1502dddf00ba2fc088238299922723cbaa.

So let me say up front, there are a bunch of overlapping issues here, and I realize that. Even when it was fresh and well-matched to Workbench 1, the tutorial text had gaps that can make it difficult to follow. And because this ticket doesn't have much description to explain what you are and aren't expected to update, it's hard for me to know what to flag in review vs. not.

Here are issues I noticed that are definitely about the parts of the tutorial that guide users through Workbench, and that I think would be straightforward to resolve. I think they're at least in the spirit of the ticket. If you have other instructions from Peter or whatever that make you feel like a specific comment is out of scope, feel free to say so. I'm filing a separate issue with non-Workbench tutorial issues I noticed.

In general, on my 4K resolution monitor, all the new screenshots of Workbench 2 are in a tight enough space that it's effectively impossible to read any text on them, making it hard to know what they're trying to show me. The text in them is about half the size of the tutorial text, maybe a little less. I would encourage you to try retaking these screenshots in a window that's about ⅓-½ the width. It could also help if the accompanying text gave more direction about what it's showing you, or if important parts were highlighted more consistently.

I retook all screenshots. Let me know if those are good enough or if I should make it even smaller. I also added more highlighting, and more text underneath the pictures.

• Section 3a "Setting up a New Project": In the text before the first screenshot, "New Project" is capitalized but the actual menu entry "New project" is not. It would be best to keep them in sync.

Fixed.

• I think part of updating the guide should include directing people to use new Workbench 2 features where they're available. In the discussion of the project UUID, the tutorial directs people to get that from the URL. However, I think most users would prefer to press the 🛈 button in the upper right for Additional info, and get/copy the UUID from there, especially since we provide a handy copy button. image7.png could help illustrate this too.

I updated the text and retook the picture (with highlighting).

• The caption for figure 6 mentions editable fields, but does not give any indication of how to edit them. I think instead of the "(editable)" parenthetical, it would be nice to add a sentence to explain that some of these fields can be edited through the Edit button in the 🛈 Additional info menu.

I added a description about how to edit.

• The caption for figure 6 mentions the collection's "content address," but Workbench 2 doesn't call it that, so this can be a confusing disconnect. It would be better to update this to say "portable data hash" to match Workbench 2.

Fixed.

• From Section 4 on: the tutorial sometimes uses Bootstrap styling to make it clear when it's talking about a specific button or UI element. With Workbench 1, the styling in the tutorial matched the UI exactly. Now it doesn't, which I think could lead to confusion or worry on the reader's part. Given that we already don't apply the styling consistently, I think I would advocate that we remove it everywhere. (If we want to revisit this, we can make a separate issue to come back and apply it consistently across the tutorial, not just on the elements that currently have it.)

I removed all Bootstrap.

• Section 4a talks about a “Run a Workflow” button that has the same capitalization problem as "New Project" above, in Workbench 2 it's just "Run a workflow".

Fixed.

• Section 4a step 1 tells you to find a workflow by searching for it. This doesn't work in Workbench 2, because the search feature does not support searching workflows. I guess for now we need to navigate to the project, then to the workflow.

I added text telling to navigate to the appropriate project first.

• Section 4a step 2 tells you to press the Run workflow button and select a project. Given this text, I was surprised when I pressed the button and was presented with an entire screenful of inputs. I think the text could be restructured to be more specific about what the flow is, and where the reader can select their project. Adding a screenshot here to highlight the input might help, since the project selection input doesn't really jump out compared to all the others on the page.

I added a screenshot and highlighted the input that needs selected.

• Section 4a step 4 says you need to scroll down to the bottom of the page but that's no longer true, the button is always visible at the bottom. The button text is now "Run Workflow" instead of just "Run" so that should be updated.

• Section 5 first option "Via the Dashboard": This option doesn't make sense anymore with Workbench 2. If Workbench 2 has a dashboard, it isn't obvious what it is. There is nothing called "Recent Processes" on the front page. At the very least, this needs to be updated to talk about "All Processes" in the left navigation menu. I think it should also be demoted to being the second option, because finding your workflow via your project is always going to be more reliable, since other users can't affect it.

I just removed this option, but let me know if you don't think that's the right call.

• Section 5 second option "Via Your Project": This is the first time the tutorial mentions the "Projects pulldown menu" so I don't know what that is. Is it meant to refer to the navigation menu on the left? The note about marking the project as a favorite is also out of date: the star icon that it refers to doesn't exist on Workbench 2. This should be updated to talk about selecting "Add to favorites" from the action menu in a listing.

I added directional text and updated instructions about updating favorites.

• In Section 5 after those steps, the paragraph about the name of the workflow doesn't seem to be up-to-date. The way the text talks about "submitted via the Registered Workflow" also feels confusing to me. "Submitted via Workbench" seems clearer and still unambiguous.

I updated the text.

• In the first screenshot of Section 6, it would be clearer if the screenshot included all of the process details. The way the screenshot is cropped now makes it look like the output collection link is at the bottom of the Details pane, which is a mismatch with the real UI.

I updated the screenshot to include the full Details pane.

• When section 6 talks about downloading the report, it would be cool to mention first that you can open it directly in your browser just by clicking the file listing. This is sort of like the project UUID thing earlier, where we can improve the tutorial thanks to a better UX in Workbench 2.

I added this text.

• Section 6, "Logs for the main process can be found in the Log tab.": In the previous paragraph, the tutorial was walking us through navigating the output collection. There's no way to get directly to the log collection from that page. A quick prompt to direct the reader to go back to the workflow process page would help prevent confusion. Being explicit about how to open the log collection would also help, because there isn't a link in the Details pane the same way there is for the output collection.

I added a more accurate description of the workflow.

• Section 6, "Now, let’s explore the logs for a step in the workflow.": Like the last comment, the previous paragraph was walking us through a collection, so a prompt to navigate back would be a helpful start. This paragraph and the paragraph that follow feel like they need their whole language and flow updated for Workbench 2. They talk about "workflow steps" where Workbench 2 consistently calls those "Subprocesses." It says "We click the arrow to open up the step, and then can click on the log collection to access the logs," but none of those UI elements exist in the Subprocess listing of Workbench 2. The tutorial talks about the subprocess bwamem-samtools-view2 but it's now called bwamem-samtools-view_2 (note the underscore).

I also added a more detailed description of the workflow.

Thanks.

In general, on my 4K resolution monitor, all the new screenshots of Workbench 2 are in a tight enough space that it's effectively impossible to read any text on them, making it hard to know what they're trying to show me. The text in them is about half the size of the tutorial text, maybe a little less. I would encourage you to try retaking these screenshots in a window that's about ⅓-½ the width. It could also help if the accompanying text gave more direction about what it's showing you, or if important parts were highlighted more consistently.

I retook all screenshots. Let me know if those are good enough or if I should make it even smaller. I also added more highlighting, and more text underneath the pictures.

These are all a huge improvement. I think the highlights are a great touch. Thanks very much for this.

• Section 3a "Setting up a New Project": In the text before the first screenshot, "New Project" is capitalized but the actual menu entry "New project" is not. It would be best to keep them in sync.

Fixed.

Thanks. Unfortunately I just noticed the caption for Figure 3 is still inconsistent, that would be good to fix.

• Section 4a step 1 tells you to find a workflow by searching for it. This doesn't work in Workbench 2, because the search feature does not support searching workflows. I guess for now we need to navigate to the project, then to the workflow.

I added text telling to navigate to the appropriate project first.

Thanks. This is definitely an improvement, but unfortunately searching for the project still raises a couple of issues:

• The search results return two copies of the project, one from pirca and one from jutro. If the reader picks the jutro one, they'll be prompted to log in again, losing their progress and kicking them off the happy path.

• The search results also return the finished demo workflow process we publish for people, "(start here) Example WGS processing workflow". This is attractive to people because it says "(start here)", has a bright green "Completed" badge next to it, and the difference between a process and a project may not be clear to people who are just getting started with Arvados.

I think it would be clearer and less error-prone to instruct people to select "Public Favorites" from the left-hand navigation, and go from there.

• Section 5 first option "Via the Dashboard": This option doesn't make sense anymore with Workbench 2. If Workbench 2 has a dashboard, it isn't obvious what it is. There is nothing called "Recent Processes" on the front page. At the very least, this needs to be updated to talk about "All Processes" in the left navigation menu. I think it should also be demoted to being the second option, because finding your workflow via your project is always going to be more reliable, since other users can't affect it.

I just removed this option, but let me know if you don't think that's the right call.

That works for me, but the opening paragraph is still written and structured like there are multiple options when there aren't anymore. IMO the simplest way to clean this up is to delete the text "If you aren’t already viewing your workflow process on the workbench, there are several ways to get to your submitted workflow. Here is the simplest way: Via Your Project:". Then let the text that's in the single bullet item become the remainder of the first paragraph.

• When section 6 talks about downloading the report, it would be cool to mention first that you can open it directly in your browser just by clicking the file listing. This is sort of like the project UUID thing earlier, where we can improve the tutorial thanks to a better UX in Workbench 2.

I added this text.

This paragraph still feels really hard to follow. Going sentence by sentence, some suggestions:

"You can directly open it in the browser by selecting the file listing." - It's not clear what "it" refers to (the previous sentence just lists all the collection's contents). Suggest: "You can open a file in the browser by selecting it from the listing."

"Additionally, by clicking on the download button to the right of the file, you can download it to your local machine." - There is no download button directly in the listing, it's a menu item available through the context or action menu. Suggest: "Additionally, you can download a file to your local machine by right-clicking a file and selecting 'Download' from the context menu, or from the action menu available from the far right of each listing."

"You can examine the outputs of a step similarly by using the arrow to expand the panel to see more details." - I honestly don't know what this is trying to tell me. At this point in the tutorial, I'm looking at a collection page, so there are no steps listed. Even if I go back to the workflow process page, and look at the subprocesses pane (note: not steps), then we're back to the comments I made last time: none of these UI elements exist in Workbench 2. If this is trying to tell me how to view subprocess output, I think it would be better to strike this sentence completely, and instead add a sentence about viewing a subprocess' output collection later in the tutorial when we talk about viewing the bwamem-samtools-view_2 subprocess. That would require less back and forth, and a lot of that text has already been updated.

• Section 6, "Logs for the main process can be found in the Log tab.": In the previous paragraph, the tutorial was walking us through navigating the output collection. There's no way to get directly to the log collection from that page. A quick prompt to direct the reader to go back to the workflow process page would help prevent confusion. Being explicit about how to open the log collection would also help, because there isn't a link in the Details pane the same way there is for the output collection.

I added a more accurate description of the workflow.

Thanks. This text is great. Please add a blank line between this paragraph and the next one so they're rendered as separate paragraphs on the web page.

Peter asked me to go ahead, make these changes, and merge as part of preparation for the 2.7.0 release. I pushed my changes to the 20497-updating-wgs-tutorial branch before merging, so they're easy to review. Please feel free to take a look, and if you have any questions or concerns or things you think we should follow up on, I'm happy to continue the conversation.