Remove documentation redundancy

[ivalaginja]

This is part of openjournals/joss-reviews#7917

1. You have redundant information between the readme and the documentation. I would recommend to consolidate, and keep everything inside the documentation only. If not, there is an increased risk of having diverging information which could lead to confusion.

What I would keep/put in the Readme:

• Very short overview, shorter than you have now.
• Link to documentation, prominently displayed
• Contributing
• License

What I would move to/consolidate with docs:

• Installation instructions and dependency info
• Quickstart and examples

2. It would also be nice to have an overview of your research/science/instrumentation case in the documentation - a brief overview of what is a starshade, how does it work, what is it used for; maybe with one figure. This doesn’t need to be longer than 2-3 paragraphs, but it would be very helpful as it explains what your code is used for in the first place. And then you can follow with all info about your code, which is currently in the overview section and reads well (both in the readme and in the docs, see comment above).

[xiaziyna]

Thanks for the comments!

1. I have cut down some of the lengthy descriptions about the package. I have a strong preference for keeping an example output, install instructions and a quickstart in the README. I think this is quite typical among small scientific software tools (e.g. https://www.pyopensci.org/python-package-guide/tutorials/add-readme.html) and helps the user to quickly get started using a package without needing to look through wordy documentation.

2. I have added in several new sections to the documentation to provide extra background and info - https://pystarshade.readthedocs.io/en/latest/content/background.html (starshade basics, optical model overview and starshade concepts).

[ivalaginja]

@xiaziyna The new sections about background info are fantastic! As for the readme, this is always a personal choice. Your changes are fine by me, I will just throw in a word of caution to look out for maintenance of both, readme and docs, and divergence between the two as you continue working on and using your package.

I consider this solved so I will close the issue.