Actions
Idea #20925
open
WGS tutorial papercuts
Start date:
Due date:
Story points:
-
Description
- There are places where the tutorial starts using an Arvados term without really introducing it. I've at least noticed this with "content address" and "process." There may be others. These concepts should be introduced just like collections are.
- Any time the tutorial tells you to find something by searching for it, it's a total mess on pirca, because you will find twenty copies of the thing that previous tutorial runners have created before you find the thing you're supposed to actually copy. The tutorial project is a public favorite on pirca. IMO we should encourage people to navigate through that for a start. I'm not sure how we introduce searching, or whether we need to.
- It's especially bad when it tells you to search for “WGS Processing reference data” and you get a lot of results for “WGS Processing Workflow reference data” and then you have to ask yourself if the tutorial is missing a word or if you just need to keep looking or what. All while you're sifting through twenty copies of both objects.
- There are a lot of bare URLs in the text, like all the Arvados links at the bottom of the intro, the tool links at the start of the next section, etc. For better accessibility we should turn these into real links. (With bare URLs, screenreaders will read the whole URL as part of the text, which basically nobody ever wants.)
- There are a lot of case consistency issues, like whether or not we capitalize CWL, YAML, other tool names, etc. Make sure the tutorial is internally consistent.
- Ditto for whether or not we
monospacetool names, log filenames, etc.
- Typo (the apostrophe makes this the wrong word): "let’s them run the workflow"
- Near the bottom where we go over
host-info.txt, the text says "We can see all the details of the virtual machine used for this step, including that it has 16 cores and 64 GIB of RAM." This is weird because the sample text included in the tutorial does not show anything about the number of cores. (The full file does have that information but I'm not sure we should bring it up without any reference to it.)
No data to display
Actions