Update documentation

[valeriocos]

The goal of this issue is to improve the documentation by adding information such as:

• context where the tool was developed (Crossminer)
• steps to run the tool
• brief description of the approach

[vchrombie]

Hi @valeriocos

I have a few doubts WRT this issue.

• steps to run the tool
• brief description of the approach

These two sections are already existing, but ya they can be improved. I can understand that.
How about having a GETTING_STARTED.md for this repository too? Just like how we had for sirmordred.

Here, the contents can be

• Execution
  • From source code repository
  • Demo Video
  • From pip package
  • Using a docker image
• How to
  • Edit
  • View
  • Visualize
  • Assess
• Tutorials
  • maybe a YouTube video explaining the steps which are done in the existing videos 🤔 WDYT?
• Import / Export 🤔 WDYT?

The How To can be improved using the microtask-9.

The rest of the things would stay at their place in the README.

Also, one more point.

context where the tool was developed (Crossminer)

I would like to know if there any references to read for writing this. 🤔

[valeriocos]

Hi @vchrombie, thank you for working on this issue!

How about having a GETTING_STARTED.md for this repository too?

I like the idea, but maybe we don't have enough content ATM.
What do you think about reshaping the readme, sketching here the different sections it should include?
Once we have the sections, we can decide to have everything in the README or move some content to the getting started.

Find below a proposal based on your suggestions

• Prosoul (with a brief description)
  • Architecture (to be added in the future)
• Installation & set up (which includes the installation and, the requirements and the steps to start the application if needed)
  • From pip package
  • From source code
  • From docker
• How to (agree with you about using the content of microtask-9)
  • Edit
  • View
  • Visualize
  • Assess
  • Import/Export
• Tutorials
  • Installation demo video
  • New video as you suggest
• How to contribute
• License

I would like to know if there any references to read for writing this

The content at https://github.com/Bitergia/prosoul#prosoul- should be enough.
References about CROSSMINER are available at https://www.crossminer.org/copy-of-papers, but there is no deliverable explaining Prosoul in depth

[vchrombie]

Hi @valeriocos

I like the idea, but maybe we don't have enough content ATM.

That is a valid point too.

What do you think about reshaping the readme, sketching here the different sections it should include?
Once we have the sections, we can decide to have everything in the README or move some content to the getting started.

Okay, this seems to be better.

The content at https://github.com/Bitergia/prosoul#prosoul- should be enough.
References about CROSSMINER are available at https://www.crossminer.org/copy-of-papers, but there is no deliverable explaining Prosoul in depth

Okay, so I assume there is nothing more to add about it as the current content is enough.

[vchrombie]

Another reply to #197 (comment)

Find below a proposal based on your suggestions

• Prosoul (with a brief description)

  • Architecture (to be added in the future)

• Installation & set up (which includes the installation and, the requirements and the steps to start the application if needed)

  • From pip package
  • From source code
  • From docker

• How to (agree with you about using the content of microtask-9)

  • Edit
  • View
  • Visualize
  • Assess
  • Import/Export

• Tutorials

  • Installation demo video
  • New video as you suggest

• How to contribute

• License

The structure seems to be perfect. I want to clarify a few more things.
So, what about the following sections, can we remove them?

• https://github.com/Bitergia/prosoul#import--export
• https://github.com/Bitergia/prosoul#requirements
• https://github.com/Bitergia/prosoul#prosoul-with-crossminer
• https://github.com/Bitergia/prosoul#prosoul-with-grimoirelab
• https://github.com/Bitergia/prosoul#roadmap

Thanks.

[valeriocos]

Thanks @vchrombie !

Okay, so I assume there is nothing more to add about it as the current content is enough.

Yes, right!

The structure seems to be perfect. I want to clarify a few more things.
So, what about the following sections, can we remove them?

Yes, but part of the content can be reused for the new structure (e.g. import/export and requirements). We could move this old content inside https://github.com/Bitergia/prosoul/tree/master/doc and see if we can take something from it after the initial reshaping. In the second iteration, we can delete it or integrate part of it. WDYT?

[vchrombie]

Thanks, @valeriocos for the reply.

Yes, right!

Okay!

Yes, but part of the content can be reused for the new structure (e.g. import/export and requirements). We could move this old content inside https://github.com/Bitergia/prosoul/tree/master/doc and see if we can take something from it after the initial reshaping. In the second iteration, we can delete it or integrate part of it. WDYT?

The plan seems to be good for me. I will work on this in the coming days and sent a PR for the first iteration.

[valeriocos]

Great, thanks!

[vchrombie]

Hi @valeriocos
Sorry for the delay. I worked on the initial revamp.

I moved a few contents like Tutorials, Prosoul with CROSSMINER and Prosoul with GrimoireLab to the doc folder.

Work needs to be done:

• A video that explains all the functions of the application, creating a basic QM and performing an assessment and replace the existing section in the Tutorial of README, once completed.

Let me know if I have missed anything.
Thanks. 🙂

[valeriocos]

No worries @vchrombie ! Thank you for your work!

Let me know if I have missed anything.

No, you didn't :)

[vchrombie]

Thanks for the merge @valeriocos.
I will complete the video and will add it here. Will close this issue after that.

I am also working on adding zulip backend to perceval parallel, so it might take some time to complete the video. 😅
Thanks.

[valeriocos]

No worries, take your time @vchrombie ! :)