Arvados

Suggestions:

• Rename "Run a pipeline using Workbench" to "Using Workbench"
• Add a "Uploading data" section under "Using workbench" with the contents of "Upload using workbench"
• Add a new "Downloading data" section under "Using workbench" which discusses how download files through the browser and use anonymous sharing links
• Rename "Working with data sets" to "Using the command line"
• Move the contents of "Run a pipeline on the command line" to "Using the command line"

Also, the white background of the workbench screenshots bleeds into the white background of the documentation pages, making it hard to distinguish where the screenshot begins and the text ends. Please add some styling so that screenshots can be clearly distinguished from the text.

Peter, I added additional details to the "Downloading data" page to talk about sharing and downloading a collection with anonymous users.

I did not rename any sections. Since Tom wanted the documentation to talk about "features" (that describe various ways of doing things) than modules, it made sense to stick with the current names and orders. Instead, I focused on adding as much detail about workbench based way of doing things (such as downloading using the share link).

I also did not like the idea of moving the workbench based sections (such as download using workbench) above the command line portion in a page. I think the command line portions have additional descriptions about the collections etc and are more meaningful when read that way. If a user does not care about command line portion or additional details about a collection, they can simply skip it and go to the workbench portions.

Please review and let me know any feedback. Thanks.

To upload a file, click on ...

Suggest "To upload files into a new collection, click on ..."

You can select multiple files. You will be able to click on the “Browse…” button multiple times and select files

Suggest changing this to "Selected files will be added to a list of files to be uploaded."

If you were to leave the collection page during the upload, the upload action will be aborted and you would need to upload again.

Suggest "If you leave the collection page during the upload, the current file upload will be aborted and you will need to upload the file again."

You will be able to use the Add data dropdown menu to add additional files to a previously collection as well.

This is confusing. I think what you want to say is "You can use the Upload tab to add files to an existing collection".

Radhika Chippada wrote:

Peter, I added additional details to the "Downloading data" page to talk about sharing and downloading a collection with anonymous users.

Looks good.

I did not rename any sections. Since Tom wanted the documentation to talk about "features" (that describe various ways of doing things) than modules, it made sense to stick with the current names and orders. Instead, I focused on adding as much detail about workbench based way of doing things (such as downloading using the share link).

Ok.

I also did not like the idea of moving the workbench based sections (such as download using workbench) above the command line portion in a page. I think the command line portions have additional descriptions about the collections etc and are more meaningful when read that way. If a user does not care about command line portion or additional details about a collection, they can simply skip it and go to the workbench portions.

I still think that workbench documentation should come first. The great majority of users (including users who are command-line savvy) are going to be looking for easy web-based upload/download first. Putting the workbench second on the page increases the likelyhood that users will get confused and not see the workbench instructions, and think that Arvados is only usable on the command line.

Tom suggests having a table of contents at the top that briefly describes and links to both options.

The "Note: This tutorial assumes either that you are logged into an Arvados VM..." is at the top of the page, but only applies to the "uploading using command prompt" / "downloading using arv" sections. It should be moved down.

Review comments for branch "4926-getting-started" and wiki page:

The "Getting started" guide looks awesome. Some minor comments below.

1. Comments about the wiki page (https://arvados.org/projects/arvados/wiki/Documentation):

• The top “there are four guides that are being developed …” section - please add missing links for the newly added “Getting started” and “SDK Reference”

• “Bugs in the documentation can be submitted as issues.” Would it be better if we add a new section “Bugs in documentation” for this rather than put it in “Contributing” section?

• “git add _config.yml _includes/_navbar_top.liquid _layouts/default.html.liquid index.html.liquid” :
  Do we want to use a new / dummy file name in this example instead?

• “The last command will throw fatal error if you’re pushing a new branch” : Do we want to say that this can be ignored?

• Code review section: a bit confusing. Earlier in the page you have link to https://arvados.org/issues/4926 . So, instead of talking about story board here can we simplify by saying add a subtask for review under your ticket for example 4926?

• “It should get reviewed shortly, if not email support@curoverse.com .” Please add a period after “shortly”

• Important files and folders: You added explanation for two of the entries (_config and default.html). Can you please add explanations for the other as well. You might want to push the explanations to a new line rather than in parenthesis to make it even more readable.

2. Comments for the branch

• Welcome to arvados page - What is arvados: “It allows you to track and your methods and datasets” => “It allows you to track your methods and datasets” (extra ‘and’)

• Welcome to arvados page - some suggestions for the gallery slider message (at the bottom of the screenshot). You can make or discard these comments as you prefer
  • “After logging in, you will see …” ?
  • “Pipelines can be also viewed” => “Pipelines can also be viewed”
  • “by changing parameters or picking …” => can we say “you can change parameters … if you want”? Basically, it can be rerun without changing anything, so I want to make sure this is not confusing
  • “which can be uploaded right in Workbench” => This was a bit confusing and it took me a second to go back to the previous slide and understand that you are talking about data sets. Can we say “Data sets can be uploaded into workbench using the Upload button”?
  • “Collections allow sharing datasets and job outputs easily” => Would it help if we add “using the Create sharing link”?

• Welcome to arvados page - Key features: can we throw in new lines between the bullet points?

• Run you first pipeline in minutes page - screenshot messages
  • “Rename the pipeline intance, then click ‘Run’. Alternatively, choose new inputs. ” => typo in “instance”. Also, can we say something like “You can change the default inputs using Choose” instead of “Alternatively…”?
  • “Click ‘Create sharing link’ to share with people outside Arvados” => Can we say to share “output” with people outside Arvados? Since this is talking about pipelines, I am not sure if it is clear that you are not sharing pipeline, but sharing the collections (output and log etc)

• Sharing data page
  • “Add data – Upload files” => “Click on Add data – Upload files”?

• Left nav -> "Simple use cases" => Can we call it "Important use cases" or something like that? I am not sure I want to say it is "Simple" :)

Thanks!

Radhika Chippada wrote:

1. Comments about the wiki page (https://arvados.org/projects/arvados/wiki/Documentation):

I did everything you recommended except move the "bugs" into it's own section, and I wasn't sure what you meant by subtasks so I just reworded it to be clear that people should just use 4926 if they're not sure.

Working on the branch now.

Hi Nancy, sorry for using my old jira terminology. Yes, I meant task by subtask. I took another look at the wiki page and yes, we just want to say for example 4926.

And can you please replace the link https://arvados.org/rb/taskboards/83 to 4926 link. Thanks.

Thanks, I updated the wiki. I also implemented most of your recommendations and pushed again.

Nancy,
Thanks for updating. Just a couple very minor comments about the branch.

• "Click ‘Add data’ — ‘Upload files’." Do you want to make it "Click ‘Add data’ —> ‘Upload files’." ? (Just replace '-' with '->' to indicate that it is two clicks)? I think this is the standard way of saying click1 -> click2 etc.

• "Click ‘Create sharing link’. You can click ‘unshare’ at any later point." Can you please capitalize "unshare"?

Thanks.

I made those changes, thanks.