cli: improve user experience

[pameladelgado]

Is your improvement request related to a use case or a component design? Please describe. The use case for the proposed improvements is based on following the first steps tutorial and playing around with Renku CLI.

Motivation For users that do not read the docs and want to enthusiastically just get started, their primary source of information is the CLI man documentation, as with any command. With this in mind, I think we should focus in maintaining a good CLI documentation at least as much as we do for the online documentation. This is particularly important if the user is working offline.

Description The following is a set of examples of where, by changing the CLI man message, the UX could be improved.

• When copying the DOI link in the tutorial example the https part is included, this is not a valid syntax for renku CLI but the provider exists. The error message could indicate the syntax instead of saying that the provider is not found.

$ renku dataset import https://www.doi.org/10.7910/DVN/WTZS4K
Error: Invalid parameter value: Could not process https://www.doi.org/10.7910/DVN/WTZS4K.
Provider not found for https://www.doi.org/10.7910/DVN/WTZS4K. Currently supporting following providers: dataverse, zenodo

• In the new release there's a distinction between the Title and the Name of a dataset. In my opinion, it would be much clearer to the user to just have NAME instead of SHORT_NAME displayed all thorough the renku dataset commands.

$ renku dataset tag mytag -h
Usage: renku dataset tag [OPTIONS] SHORT_NAME TAG

what does short name means? what would be the long name? (I was confused at the beginning then I understood that the title might be a long sentence)

• While adding a large dataset on another tab and trying to add a small one:

$renku dataset add notebooks/filtered-flights.csv 
Ahhhhhhhh! You have found a bug.
filelock.Timeout: The file lock '/work/qa-flights-tutorial/.renku.lock' could not be acquired.

• What does TEXT mean here? is a revision the same as commit sha? (a hint I got after checking the documentation)

Options:
  --revision TEXT

• Would it make sense to add examples in some -the most important/common- renku command cases?

• When importing a big dataset the user does not get any feedback, the cursor is there stuck. It would be good to know that its importing or see a progress bar if pertinent.

• After importing a file the progress bar disappears, this was unexpected

• why is one tag created by renku import? called 1? does it indicate a version? why do I have a different commit sha when I add a tag?

CREATED              NAME    DESCRIPTION                    DATASET             COMMIT
-------------------  ------  -----------------------------  ------------------  ----------------------------------------
2020-02-27 13:38:19  1       Tag 1 created by renku import  2019-01 US Flights  dd9c2dce5f45b485b41f2b403da0d8d0969e0404
2020-02-27 13:47:13  mytag                                  2019-01 US Flights  68d36d9e6c2325a1ff40b4bbecd422616e34a468

[jsam]

Thank you @pameladelgado for your feedback and extensive discussion we had. I took liberty to break this down into more manageable and smaller pieces which could be addressed as we go.

Tickets can be found here:

• #1077
• #1078
• #1079
• #1080
• #1081
• #1082
• #1083

edit: Let me know if I have missed something.

[pameladelgado]

the issues look great, thanks a lot @jsam !

[rokroskar]

I added the issues above to the epic