Improve docs/Contribute.md

[pleia2]

One of the ways we can make new contributors feel more welcome and onboard more quickly is by creating a friendly, comprehensive contribution guide. We have a basic start at docs/Contribute.md but it could be improved significantly.

A few thoughts about what to add:

• "Tour" of the repositories (this one, plus -data and -deploy)
• Link to our contact information (probably just linking to our README, but this could be improved too by adding a link to our calendar and maybe other places?)

[deadaf]

Hello @pleia2 , I would like to contribute to this issue. I came across this repository while searching for a LFX mentorship program, and I'm delighted to inform you that I have applied for the same.I'm eager to contribute to the project in any way I can.

Could you please provide me with a list of sections to add in the CONTRIBUTING.md file? Thank You!

[pleia2]

Thanks for your interest, @deadaf!

The "tour" I referenced above was explaining that there are 3 repositories for the Software Discovery Tool.

1. https://github.com/openmainframeproject/software-discovery-tool
2. https://github.com/openmainframeproject/software-discovery-tool-data
3. https://github.com/openmainframeproject/software-discovery-tool-deploy

For the first two you can use a version of the README for the documentation to explain what each repository does. For -deploy you can borrow some language from this gist https://gist.github.com/rachejazz/de39c09612788635d5d0f491dcf8571a

The idea with this "tour" is we first want to get developers familiar with the structure of the project so they understand that there are 3 repositories, and that they each serve a specific purpose.

The next is explaining that these projects are part of the Linux Foundation Open Mainframe Project and so abide by the Contribution Guidelines set forth at https://tac.openmainframeproject.org/process/contribution_guidelines.html and also mention that contributions are always reviewed by another member of the project.

In the conclusion of this document, you can link back to the README for how to collaborate with the rest of the team.

Additionally, this is where having fresh eyes to the project will really help out. When you learned about this project, what did YOU want to know about contributing? If you have any questions, I'm happy to answer them so we can either incorporate them into this document (if applicable) or other documentation in the project.

[deadaf]

Thanks for the clarification @pleia2 , This issue clearly makes sense as when I first visited this project, it wasn't really clear to me what's going on and where should I even begin, the major reason for all this acc to me is the incomplete README which clearly requires a rewrite.

The README explains the project in just one line and mentions terms like zArchitecture/s390x and Z operating system and doesn't really explain what they are, making it confusing for developers who are new to the project.

Generally we find a CONTRIBUTING.md file in root dir of repositories which makes a lot of sense because it makes understanding contributing guidelines very easy for new developers, but in this case the file is actually inside the docs dir and that too isn't mentioned anywhere in the README.

I suggest the following changes:

In README

1. Improving the Overview section by adding more information about the project itself.
2. Add a section about contributing that links to the docs/Contribute.md.

In docs/Contribute.md

1. Add the "tour" section as you suggested.
2. Moving the existing info under a separate section maybe Getting Started.
3. Mentioning the openmainframe contributing guidelines as you suggested.
4. Add a new section "Code Standards" suggesting code standards (maybe mentioning PEP 8 style guide), a state of the art linter maybe, flake8 and a formatter like black.

Please let me know if I am on the right track and the changes I suggested aligns with your expectations. If so I will be more than happy to work on the issue and open a PR.

Thank You!

[pleia2]

This all sounds great! The only thing I'd hold off on is the part about Code Standards since the details of what approach we want to follow are still being discussed in #117.

[deadaf]

Thanks @pleia2, I will soon make a PR with the discussed changes.