Improve examples description and structure

[pkosiec]

Resolves #25
Related also to the discussion in #19

[mjgs]

I've reviewed the updates as per your request. I still find the text confusing. Here are my observations and recommendations:

Although you call the tutorial page a tutorial when you link to it, the title of the page ("Import data definition") doesn't reflect that it's a tutorial, and I would say after reading the page, it isn't really a tutorial (specific steps to take to accomplish a result), it's more a description of the functionality.

A lot of the info on the tutorial page is already on the main page anyway.

The samples page feels more like a tutorial to me.

Maybe you should rename the Samples page Tutorial, and merge in all the old tutorial page into the main page, then remove the old tutorial page. It's just a suggestion, that's what I would do. I hope this is helpful to you.
[Updated: for clarity I reworded "tutorial page" to read "old tutorial page" in the above paragraph]

[pkosiec]

Thank you @mjgs for review! Are you sure that you've seen the latest content? There is no samples directory anymore - this pull request changes it. You can see the updated repository content here: https://github.com/pkosiec/mongo-seeding/tree/9a56e9730d2ce4d22d05eee1e17db221b2721340

[mjgs]

@pkosiec yes I've seen the changed folder name, in my opinion the project needs more than a simple folder name change to make it understandable and accessible for users.

[pkosiec]

@mjgs No, it wasn't only directory rename, I've written detailed instruction for every example from a scratch, including the one for custom Docker image. There shouldn't be confusion anymore, how to run examples. That was your main concern and that's why I've rebuilt this section.

Your points about data import tutorial were valid, so I adjusted that file as well in this pill request. However, I don't want to move it to main readme, because it has too much details - on main "page" user should meet just the basics, get the overall idea.

[mjgs]

@pkosiec You know the docs are definitely getting better! I can see you've made a lot of changes. The "import data definition link" is broken on the main page. In case you are not aware, that page also says tutorial in the title, not sure if you wanted to remove the tutorial word or not.

Something else I noticed, the example import pages lists Docker under Prerequisites, which is only the case presumably for when using the docker import method, right? If a user that is only wanting to use the cli method gets to that page, then that could be a road block for them.

[pkosiec]

The "import data definition link" is broken on the main page.

Good catch! Fixed.

In case you are not aware, that page also says tutorial in the title, not sure if you wanted to remove the tutorial word or not.

Right, I switched to "guide".

Something else I noticed, the example import pages lists Docker under Prerequisites, which is only the case presumably for when using the docker import method, right? If a user that is only wanting to use the cli method gets to that page, then that could be a road block for them.

You're right! I've marked all the tools optional, because as you noticed they are not required.

Mark, many thanks for your contribution! You helped me a lot with the docs. I will merge this, but if you have any other ideas, suggestions or issues, please do not hesitate to contact me or write an issue 🙂 Again, a huge thank you!