Improve Docs

[pottekkat]

The docs of learningOrchestra need to be validated, tested and improved by test users. The doc could be the README and the docs page.

[LaChapeliere]

Hi, I'm happy to help with the doc, because I had trouble understanding what the project was about when looking through the readme. Focussing on user doc (rather than dev doc), I'm proposing to go over the Readme with the view of a user who knows how to do data mining scripts but might not be familiar with infrastructure, cloud services, microservices...

[LaChapeliere]

Proposed outline:

1. One-sentence summary
2. Thumbnail and indicators
3. Introduction: what is the project, who is it for, why should I use it?
4. Table of Contents
5. Quick-start
6. Installation instructions
7. Usage instructions
8. About learningOrchestra

[LaChapeliere]

I'll start a branch and update here when I'm missing info

[pottekkat]

@LaChapeliere Thank you for contributing. Sure you can make the changes to the README and the docs repo. You can maybe start a draft PR so we can track the progress.

[LaChapeliere]

First question, probably for @riibeirogabriel
"learningOrchestra facilitates and streamlines iterative processes in a Data Science project pipeline " but "learningOrchestra is a distributed Machine Learning processing tool"
After reading your monograph, I think I understand why you used data science in one case and machine learning in another, but for user-friendliness purposes, I strongly recommend picking one to describe your project. Personally, I'd use data science/data mining because you're talking to data scientists. Then you can refer to machine learning methods for analysis microservices, of course

[pottekkat]

I think so too. I also think that the exact purpose of this project gets lost somewhere in the docs. How can we clear things in the README and the docs?

PS: We can first fix the README and then move on to the rest of the docs.

[LaChapeliere]

@navendu-pottekkat I've shared a first proposition for the intro in this draft PR ⬆️
You are right, let's not try to change everything at the same time. Plus improving the docs requires to understand the code so it's more work ^^

[riibeirogabriel]

First question, probably for @riibeirogabriel
"learningOrchestra facilitates and streamlines iterative processes in a Data Science project pipeline " but "learningOrchestra is a distributed Machine Learning processing tool"
After reading your monograph, I think I understand why you used data science in one case and machine learning in another, but for user-friendliness purposes, I strongly recommend picking one to describe your project. Personally, I'd use data science/data mining because you're talking to data scientists. Then you can refer to machine learning methods for analysis microservices, of course

Yep, I also guess. We can make the readme with data scientist porpose, the "distributed machine learning processing tool" was provided in project begin, when us wanted make a distributed tool, but this mindset was changed.

[LaChapeliere]

First question, probably for @riibeirogabriel
"learningOrchestra facilitates and streamlines iterative processes in a Data Science project pipeline " but "learningOrchestra is a distributed Machine Learning processing tool"
After reading your monograph, I think I understand why you used data science in one case and machine learning in another, but for user-friendliness purposes, I strongly recommend picking one to describe your project. Personally, I'd use data science/data mining because you're talking to data scientists. Then you can refer to machine learning methods for analysis microservices, of course

Yep, I also guess. We can make the readme with data scientist porpose, the "distributed machine learning processing tool" was provided in project begin, when us wanted make a distributed tool, but this mindset was changed.

I'll write the Readme from that perspective, and you can decide whether to change the motto and thumbnail later on that way

[LaChapeliere]

@riibeirogabriel I'm trying to figure out the installation process. There's one big thing that is unclear for me: you mention Linux hostS and clusters, so I'm guessing you can run learningOrchestra in multithread over several machines? If that's the case, how/where do you link the machines together?
Also, you need to already own the machines on which you are running learningOrchestra, right? So you have to rent some VMs from some cloud provider first? Do you plan to add a feature where learningOrchestra can facilitate that?