[Documentation] (recurring) Refresh user documentation
#5 Updated by Brett Smith over 5 years ago
- 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.
#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.