Arvados

I addressed these points as below

details¶

1a) where to get file var-GS000016015-ASM.tsv.bz2

http://doc.arvados.org/user/tutorials/tutorial-keep.html#upload-using-command

I think someone else fixed this already, but I detailed two more ways around this just in case.

1b) there also "Locate your collection in Workbench" makes a wrong reference to "projects" -> "Home" actually is

"my account" > "home project"

This is actually correct, you can access the home project both ways.

2) already-mounted Keep

I didn't do anything to address this -- I don't see any issue, since it doesn't hurt to re-mount Keep. Maybe you can specify a "Note" that would have made this less confusing?

3) CSS misleading button hover effect

I'll put this aside for now -- although definitely not ideal, I don't think it's a "blocker" per se

4) (If you are using a different Arvados instance than the default for this guide, replace workbench.qr1hi.arvadosapi.com with your private instance in all of the examples in this guide.)

I created doc/_includes/_tutorial_cluster_name and updated http://doc.arvados.org/user/topics/running-pipeline-command-line.html

5) Example pipeline run fails

http://doc.arvados.org/user/topics/arv-run.html

• human_g1k_v37.fasta:
  ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/technical/reference/, specifically ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/technical/reference/human_g1k_v37.fasta.gz

• HWI-ST1027_129_D0THKACXX.1_1.fastq HWI-ST1027_129_D0THKACXX.1_2.fastq:
  https://workbench.qr1hi.arvadosapi.com/collections/qr1hi-4zz18-prwmlm69rn1zpbp

In th end, turns out this is a bug, #5990, which will be addressed over the next week or so.

6) better picture on technical overview of system

I added the page from the whitepaper to the wiki. https://arvados.org/projects/arvados/wiki/Technical_Architecture

7) less confusing "workbench getting started" situation (too many options right now)

#7 is a bigger story / task, so I'll leave it for later and push the changes listed above for now..

Note to self: How to make a blue dismiss-able "note" box¶

make a file in /_includes, for instance _tutorial_expectations.liquid

Line 1: {% include 'notebox_begin' }
Line n: { include 'notebox_end' %}

to put the notebox in a tutorial, use

{% include 'tutorial_expectations' %}

Branch 5930-smalldocfix now up for review.

Review comments:

• doc/_includes/_tutorial_cluster_name.liquid
  • Not sure if we should mention su12l in general user documentation? I think we can instead use the wording used by user/getting_started/workbench.html: If you are using a different Arvados instance than the default, replace qr1hi with your instance

• user/topics/running-pipeline-command-line.html
  • Please move the tutorial_cluster_name note to the top of the page. Saying it early on accomplishes your goal of communicating this with the user before it caused much confusion.

• user/topics/running-pipeline-command-line.html
  • Same as above. Please move the tutorial_cluster_name note to the top of the page.

• user/topics/arv-run.html
  • Should we include the following in the Redirection section as well? It appears that this is the only one missing it now.
    

    $ <span class="userinput">cd ~/keep/by_id/3229739b505d2b878b62aed09895a55a+142</span>
    $ <span class="userinput">ls *.fastq</span
    

• user/tutorials/tutorial-keep.html
  • The file used in this example is a freely available TSV file … : Can you please throw in “the” before “Personal Genome Project”? Also, this sentence is a mouthful. Consider breaking it up into more sentences: “The file used in this example is a freely available TSV file containing variant annotations from Personal Genome Project participant hu599905). It can be downloaded from here.”

• Few concerns about the arvados/wiki/Technical_Architecture update
  • Clicking on the architecture diagram area takes me to the image page. The picture in “Details” area does not do that. Can you please use the same link format as this for the architecture diagram so that it is not confusing and no jumping around?
  • Can you make the image take more space? It is too small now and almost unreadable without clicking on it (which has the above concern). Probably same as the one Details section or 80 to 90%, whatever works.
  • Can you please remove the page number 6, top right border etc from the image. I actually think you can remove the title also from it and select just the content area of the page to generate this image. That should make it lot more readable by occupying all the available real estate.

Some other comments:

• I marked this issue as "In progress" and updated the target version. This helps us not forget to mark it as resolved when done. Thanks.

• I also added the review task for the ticket.

Changed as per Radhika's comments and merged to master.