I expect most contributors to start with CONTRIBUTE.rst as their first point of entry. Ideally, I would expect this document to guide linearly through everything that’s required for a contribution. And it does, except for setting up the development environment. The only reference is a brief sentence in “Testing” that points at the installation guide without a link. I just kinda assumes that contributors started with the installation guide. However, the “Installing scikit-image for contributors” in INSTALL.rst assumes that you already forked and cloned scikit-image (and know how to). There are more issues stemming from this, e.g. CONTRIBUTING.rst instructs to run pre-commit install without mentioning how to get pre-commit into your current shell.
So I think there is some room for improvement. I’d like to be able to point at INSTALL.rst if a user asks me “How do I get a working installation of scikit-image on my machine?”. And I want to be able to point at CONTRIBUTE.rst if someone asks “How to I contribute my suggestion, idea, or code to scikit-image?”
Ideally, I’d like both documents to be stand-alone in the sense, that users/contributors don’t have to leave the document to answer most of the question and link both documents where it makes sense.
This also touches on our “Install from Source” section in our README.rst. That should probably just link at the proper guide.
What do you think? I’m itching to make a PR but I wanted to make sure this is not controversial beforehand.
from me to your suggestions.