I'm reading through the user guide and trying to match the descriptions to implementations as I go, and I wonder how y'all are imagining this relatively slippery question of "User to developer experience"? Put another way -- what are your goals for having someone who is just using the package to be able to read the source and contribute to it? I think "we don't" is a fair answer, as it's by far the most common way software is structured, but just wanted to check.

Concretely, As I'm reading, I'm on the "fundamentals" page looking at the behavior of the overridden lshift operator ( https://python-graphblas.readthedocs.io/en/stable/user_guide/fundamentals.html#update-notation ) and trying to figure out where that's implemented in the code. I just did a ctrl+f for def __lshift__, but is the goal for the aspiring-developer-user to be able to back their understanding up into the code?

I feel like i'm not being clear here, so maybe another way of asking this question is how should someone go from reading the docs to reading the code? When I open the graphblas directory, how am I intended to understand what the submodules are doing? Since the API docs are not isomorphic with the project structure (which is fine) this is sort of challenging - there isn't a corresponding page in the docs that would tell me how the graphblas.core.base module works, for example.

If the goal is to make it easy for people to understand implementation (again, fine if that's not a primary goal) then i would def recommend having some additional description of how the package is organized. That would probably be best done in docstrings in the modules themselves, and then using automodule rather than writing a whole ton of narrative docs separate from the code, but i'm ultimately agnostic about the implementation.

edit: part of pyOpenSci/software-submission#81