Feature #4926

[Documentation] (recurring) Refresh user documentation

Added by Tom Clegg about 4 years ago. Updated almost 4 years ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Radhika Chippada
Category:
-
Target version:
Start date:
01/09/2015
Due date:
% Done:

100%

Estimated time:
(Total: 0.00 h)
Story points:
1.0

Subtasks

Task #4787: [Documentation] Mention browser-based upload featureResolvedRadhika Chippada

Task #4955: Review branch: 4926-browser-based-uploadResolvedPeter Amstutz

Task #5038: Review branch: 4926-getting-startedResolvedNancy Ouyang

Associated revisions

Revision e6c0c056
Added by Radhika Chippada about 4 years ago

refs #4926
Merge branch '4926-browser-based-upload'

Revision 32002eb6
Added by Nancy Ouyang about 4 years ago

refs #4926 Merge branch '4926-getting-started'

Revision fb4921f5
Added by Nancy Ouyang almost 4 years ago

refs #4926 #5072 Merge branch '4926-fix-imagesizes'

Revision bd53829c
Added by Nancy Ouyang almost 4 years ago

refs #4926 Merge branch '4926-rename-share.png'

History

#1 Updated by Brett Smith about 4 years ago

  • Assigned To set to Brett Smith

#2 Updated by Brett Smith about 4 years ago

  • Assigned To deleted (Brett Smith)

#3 Updated by Peter Amstutz about 4 years ago

  • Assigned To set to Peter Amstutz

#4 Updated by Peter Amstutz about 4 years ago

  • Assigned To deleted (Peter Amstutz)

#5 Updated by Radhika Chippada about 4 years ago

  • Assigned To set to Radhika Chippada

#6 Updated by Radhika Chippada about 4 years ago

  • Status changed from New to In Progress

#7 Updated by Peter Amstutz about 4 years ago

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"

#8 Updated by Peter Amstutz about 4 years ago

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.

#9 Updated by Radhika Chippada about 4 years ago

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.

#10 Updated by Peter Amstutz about 4 years ago

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".

#11 Updated by Peter Amstutz about 4 years ago

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.

#12 Updated by Peter Amstutz about 4 years ago

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.

#13 Updated by Radhika Chippada about 4 years ago

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 .” 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" :)

#14 Updated by Nancy Ouyang about 4 years ago

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.

#15 Updated by Radhika Chippada about 4 years ago

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.

#16 Updated by Nancy Ouyang about 4 years ago

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

#17 Updated by Radhika Chippada about 4 years ago

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

In the 'Sharing Data' page:
  • "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.

#18 Updated by Nancy Ouyang about 4 years ago

I made those changes, thanks.

#19 Updated by Radhika Chippada almost 4 years ago

  • Status changed from In Progress to Resolved

Also available in: Atom PDF