Feature #5247

[Documentation] (recurring) Refresh user documentation

Added by Ward Vandewege almost 6 years ago. Updated over 5 years ago.

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

100%

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

Subtasks

Task #5248: [Documentation] Add public projects (anonymous access) to documentation.ResolvedRadhika Chippada

Task #5557: Review branch: 5247-anonymous-docResolvedRadhika Chippada

Associated revisions

Revision 4f6b424e
Added by Radhika Chippada over 5 years ago

refs #5247
closes #5248
Merge branch '5247-anonymous-doc'

History

#1 Updated by Radhika Chippada almost 6 years ago

  • Assigned To set to Radhika Chippada

#2 Updated by Tom Clegg over 5 years ago

  • Target version changed from 2015-03-11 sprint to 2015-04-01 sprint

#3 Updated by Radhika Chippada over 5 years ago

  • Status changed from New to In Progress

#4 Updated by Radhika Chippada over 5 years ago

About 5247-anonymous-doc branch implementation:

The anonymous documentation is added in the 'Getting started' guide under 'Quickstart' section.

#5 Updated by Brett Smith over 5 years ago

Reviewing b01a47b

  • The intro paragraph says, "By visiting this project, you can see what an Arvados project is, access data collections in this project, click through a pipeline instance contents." This sentence could use an "and" before "click through" to introduce the final clause of the list. The end of the sentence has a problem with number agreement; it reads as "a… contents," which mixes up singular and plural. I think a good fix would be to make the instance possessive: "click through a pipeline instance's contents;" then "a" modifies "instance."
  • The screenshot captions are not consistent in the way they refer to tabs by name. Some names are capitalized, and others aren't; some names are in single quotes, and others aren't. Please choose a single convention and use it consistently. I think bold tab names would best fit within the existing documentation conventions (referring to a page element you should look at or interact with), but I understand if you feel that's not suitable for captions.
  • Similarly, I think it reads better when the captions use the definite article "the" to refer to a specific tab or page: "the Data collections tab," "the Collection page," etc. This is missing in captions 2 and 4 for tabs, and 5 and 6 for pages.
  • Caption 6 says, "Collection ‘Provenance graph’ gives a visual representation of the collection contents." I'm concerned this may lead users to believe that the graph provides some representation about the files in the collection, when what it shows is provenance information about how the collection is created. Do you think there's a way to clarify this?
  • This is a small thing and subjective, but I think the screenshot for the Advanced tab in the last slide might be more visually interesting and helpful if it showed the API response pulled down. If you don't agree, though, the current version is fine.

Thanks.

#6 Updated by Radhika Chippada over 5 years ago

Brett: made all the suggested updates. As for the last comment, I left the Advanced tab slide as is because once I expand the API response, the other options get hidden. Thanks.

#7 Updated by Brett Smith over 5 years ago

Radhika Chippada wrote:

Brett: made all the suggested updates. As for the last comment, I left the Advanced tab slide as is because once I expand the API response, the other options get hidden. Thanks.

Thanks. Just two small fixes from here:

  • Caption 6 ends with two periods.
  • Caption 11 says, "The Graph tab gives a visual representation of the pipeline run." The verb "gives" needs an object, so it should either say "gives you a visual representation," or this should use a different verb like "provides."

This is good to merge with those fixed. Thanks again.

#8 Updated by Radhika Chippada over 5 years ago

  • Status changed from In Progress to Resolved

Also available in: Atom PDF