[FEATURE] Improved QuickStart and CLI documentation suggestions

[bijanfx]

Problem background: First time user, needing to ssh into an Ubuntu Lambda machine to do CLI based work.

Solutions tried: Tried to use MC command line docs, found here and here

Suggestions for documentation improvement, which currently only describe 3 Steps:
It would be nice if the docs went past Step 3 "Test the Connection" with:
Step 4: Create a Bucket
Step 5: Copy a local file to the bucket
Step 6: Copy an object from the bucket to a local drive.

During step 5, a newbie might forget to include the bucket name. The error returned is: "Unable to upload. Bucket should not be empty". This was confusing, and could easily be interpreted as the bucket has no object in it, it is empty. A better wording would be: "Error: Bucket name not specified"

Additionally, for command line errors, it would be helpful and convenient if a usage line accompanies the error message, with an example of how the command line should be constructed. See examples below.

Below is what the MIN ai-chatbot returned as steps I mentioned above

1. Creating a bucket: USAGE: mc mb <your_minio_alias>/<new_bucket_name>/
   Example: mc mb myminio/newbucket/

2. Copying a local file to the created bucket: USAGE: mc cp <local_file_path> <your_minio_alias>/<new_bucket_name>/
   Example: mc cp /path/to/local/file.txt myminio/newbucket/

3. Copying a file from the bucket to the local filesystem: USAGE: mc cp <your_minio_alias>/<new_bucket_name>/<file_name> <local_directory>
   Example: mc cp myminio/newbucket/file.txt /path/to/local/directory/

DIFFERENT TOPIC

It probably would be more professional and self-explanatory if the in the command line --help results, the terminology followed the examples above. For instance, for mc put --help the returned text used words like play/mybucket . It is not at all clear nor defined what play means.

DIFFERENT TOPIC

mc ls --help contains no examples of how to list files in a minio local deployment. They're all s3/ deployments. What if the user (me) is not using S3 ?

DIFFERENT TOPIC

Why does mc ls list local files? I thought because it is a mc command it would list the deployment buckets, files, etc. It becomes confusing. It should probably return an error, that no deployment and bucket was specified. And give a USAGE example when that error happens. If mc ls and unix's own ls do the same thing, then......why?

It probably would be a good idea to make a pass through the --help of all the mc command and apply the notes above, if desired. Some have examples, some don't. Consistency would be an excellent addition. :-)

[djwfyi]

@bijanfx It seems like most of the items above have to do with the mc command line --help results, which is maintained in the minio/mc repo. All of the output you see on screen would need to be done in that repo.

This repo is specifically the web based help found at https://min.io/docs/minio/linux/reference/minio-mc.html (for the mc reference docs).

[bijanfx]

Hi @djwfyi . Ah. Ok, thanks ! :) I'll resubmit in that repo.

Actually, my main wishlist / suggestion is in expanding the online docs to have a step 4,5,6. That I think can stay in this repo's suggestion box (?)

[djwfyi]

The problem with adding the steps 4-6 you suggest to the web docs is that not everyone who installs mc is going to need to do those things. Possibly not any of them.

It's impossible to know what the person installing the MinIO Client needs to do with the client next.
If they are a new admin or user of an existing implementation, or just someone with a new PC, none of those may be a logical next step.

The quickstart page is about getting MC installed and connecting it to the desired deployment. And that's done and confirmed in the three steps. What happens next could be anything that MC is capable of. Maybe they need to set up a user. Maybe they need to mirror something. Maybe they need to remove a bucket. Maybe they need to set up tiering. All of those could be next steps for the user.

As noted above, the rest of the suggestions need to be done in the minio/mc repo. So I'll close this issue.

[djwfyi]

Note on issue transfer:
The first half of the issue description was a suggestion for the documentation team.
The other half (staring with the "Different Issue" headings) is content that needs to be handled in the minio/mc repo.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

[klauspost]

Closing. Most of this is just in-actionable questions anyway.