COMPILING.md, CONTRIBUTING.md and other docs's need a major update

[pgScorpio]

Describe the bug

COMPILING.md, CONTRIBUTING.md and other documentation is incomplete and unclear for new contributors.
To Reproduce

Just one simple example:
There are several make commands suggested in the documentation, but nowhere is stated that you have to run qmake Jamulus.pro before you can use any make command like make clang_format.

Also there are many prerequisites mentioned like Qt, Visual Studio and XCode, but nowhere is mentioned which versions they should be and where/how to get them (some are very hard to find!) and which options to install (many are not default, but some are essential).
Even some very essential tools (like git and clang-format) aren't even mentioned at all.
Also the "more information" links often send you in circles, referring back to where you came from.
i.e. CONTRIBUTING.md points to this page which contains not much more information than a link back to CONTRIBUTING.md.
Expected behavior

For a new contributor it should at least be clear what to install, with what options, and where to get it.
For the "old" contributors It may all seem seem obvious, but for newbies, like me, even as a very experienced software engineer, It is a real struggle to get everything installed and working.
Screenshots

Operating system

n.a.
Version of Jamulus

n.a.
Additional context

[ann0see]

Thanks!

I think #2289 is related.

So what's the actual todo list?

• Add Comment to run qmake before being able to run clang_format
• Drop link to contributing page on Website
• Document earliest supported macOS version
• Re-Write the compilation guides to look more like a guide, not like a "you need that" and then compile as you wish style

Anything else? Please add this checklist to your initial issue description

[ann0see]

@pgScorpio I think the last thing missing here is an update of the circular dependency on the website? Can you open an issue on the website repo for that?

[pgScorpio]

@pgScorpio I think the last thing missing here is an update of the circular dependency on the website? Can you open an issue on the website repo for that?

Well I don't know if that's just a website problem, since it's github md files pointing to the wiki and the wiki pointing to the github md files....
It seems logical to refer to the md files from the wiki (And I think they should ONLY do that.).
But, though it seems logical that CONTRIBUTING.md, points to the wiki, the wiki does not provide much more information than already in CONTRIBUTING.md, and the wiki finally points back to CONTRIBUTING.md.

So if CONTRIBUTING.md already has all the information that is on the wiki page (Basically the links raise it as a bug, post about it on this forum, documentation and translation process, introduce yourself, and I think most of them already are) The wiki could just only link to CONTRIBUTING.md and there would be no need to link to the wiki from CONTRIBUTING.md.

So if all this information is indeed in CONTRIBUTION.md we could change the wiki contributing page to just point to CONTRIBUTION.md.

[gilgongo]

it's github md files pointing to the wiki and the wiki pointing to the github md files....

I can't see where that's happening - can you explain?

BTW the content on https://jamulus.io/wiki/Contribution was written for people who don't know or care about coding, so links to Github for those people are potentially off putting perhaps. Mind you, you can't contribute to Jamulus without using Github so maybe that's moot.

[pgScorpio]

I can't see where that's happening - can you explain?

OK, so the link to the wiki is no longer there in CONTRIBUTING.md ??

BTW the content on https://jamulus.io/wiki/Contribution was written for people who don't know or care about coding, so links to Github for those people are potentially off putting perhaps. Mind you, you can't contribute to Jamulus without using Github so maybe that's moot.

Wiki says:
Want to contribute code?
See our guidelines for getting involved in development.