Closed rmorgan10 closed 3 years ago
Hi, I agree with @rmorgan10. For me, there is a gap between the high-level software description in the docs/paper and the examples which jump into to specific applications. I think the suggested text in the docs/paper could also benefit form a discussion of the following points:
Resolved by #456 and #460. Closing
After some time digging through the code and documentation, I was able to piece together that SkyPy is useful for quickly obtaining realistic distributions of galaxy shapes, redshifts, luminosities, photometry, and masses (perhaps there are more physical quantities that I missed). If that list of features / use cases were clearly presented, it would eliminate the need for interested astronomers to dig through all the code / examples / documentation to determine whether SkyPy will be useful in their analysis.
I recommend 2 ways of conveying all of SkyPy's uses to potential users:
and
Examples: Galaxy Morphology Distributions Galaxy Redshift Distributions
The page https://skypy.readthedocs.io/en/latest/galaxies.html almost accomplishes this goal for the skypy.galaxies package, but the only descriptions included are "The following modules are found in the skypy.galaxies.* package." I think a potential user may want some expanded descriptions of how a particular module will be relevant to their analysis.
The page I think would be useful would contain all packages in SkyPy (at present galaxies, utils, and pipeline) and use "astronomer-friendly" language (not function names) to describe the feature, and then link to the page in the documentation. All the features are documented thoroughly, but it would be nice to have some sort of reference page for all the things SkyPy can do.
After seeing some of the other issues in this repo, it's clear that the main functionalities of SkyPy will be expanding, so that is even stronger motivation to have a page like this.