Bug #5930

[Documentation] Misc. documentation fixes

Added by Nancy Ouyang over 4 years ago. Updated about 4 years ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Nancy Ouyang
Category:
Documentation
Target version:
Start date:
05/17/2015
Due date:
% Done:

100%

Estimated time:
(Total: 2.00 h)
Story points:
-

Description

As listed by Nico:

  • a graph/diagram of the infrastructure will be a nice to have for future
    sysadmin
  • fix new user experience so that there is only Curated collections / pipelines on their first login to Curoverse -- otherwise they will be confused (which pipeline to run?). Potentially have a large "unlock level 1" button.

Nancy's opinions:


Subtasks

Task #6052: Review branch: 5930-smalldocfixClosedNancy Ouyang


Related issues

Related to Arvados - Bug #5947: [Workbench] Provide additional guidance to users running their first pipelineNew05/07/2015

Related to Arvados - Bug #5946: [Workbench] "other collections have the same content" page is confusingNew05/07/2015

Associated revisions

Revision 78ddad37
Added by Nancy Ouyang about 4 years ago

closes #5930. Merge branch '5930-smalldocfix'

History

#1 Updated by Nancy Ouyang over 4 years ago

  • Description updated (diff)

#2 Updated by Nancy Ouyang over 4 years ago

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

I cleaned up a few typos and made sure the files are referenced properly --

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' %}

#3 Updated by Nancy Ouyang over 4 years ago

Branch 5930-smalldocfix now up for review.

#4 Updated by Radhika Chippada over 4 years ago

  • Target version set to 2015-05-20 sprint
  • Subject changed from Misc. documentation fixes to [Documentation] Misc. documentation fixes
  • Category set to Documentation
  • Status changed from New to In Progress

#5 Updated by Radhika Chippada over 4 years ago

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.

#6 Updated by Brett Smith over 4 years ago

  • Target version changed from 2015-05-20 sprint to 2015-06-10 sprint

#7 Updated by Nancy Ouyang about 4 years ago

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

#8 Updated by Nancy Ouyang about 4 years ago

  • Status changed from In Progress to Closed

#9 Updated by Nancy Ouyang about 4 years ago

  • Status changed from Closed to In Progress

#10 Updated by Anonymous about 4 years ago

  • Status changed from In Progress to Resolved
  • % Done changed from 0 to 100

Applied in changeset arvados|commit:78ddad37d72c6c3a728530dc6932fb91f7d81b87.

Also available in: Atom PDF