search

shirtsgroup / physical_validation

Physical validation of molecular simulations
https://physical-validation.readthedocs.io
MIT License
55 stars 19 forks source link

Make sure that documentation is beginner-friendly #49

Closed ptmerz closed 3 years ago

ptmerz commented 4 years ago

Ideally, the documentation should allow users having moderate knowledge of molecular simulations to run tests on their systems within a few minutes. It should then have additional information for users interested in the details of theory or implementation. It would be very helpful if group members that have little or no knowledge of the physical validation package could verify if the current documentation is beginner-friendly, and suggest improvements!

wehs7661 commented 4 years ago

I'm happy to get involved with this if needed!

schwinns commented 3 years ago

I should be able to start using it this week (like Wed. 2/3), and I'll make notes as I go.

wehs7661 commented 3 years ago

I will run some simple tests using the package by this weekend to share my thoughts by this weekend (Feb. 7).

schwinns commented 3 years ago

Overall, I think the docs are pretty clear. The examples make it easy to quickly get results. I worked through all the examples and then tried it on some simple simulations. I only had a couple suggestions, and I was not sure what would be the best way to make them. (I could try a pull request, but I don't know how to make all the edits I am suggesting).

  1. Include matplotlib in the installation. This is not super important since most everyone uses matplotlib, but I created a new environment and ran into errors (even when not attempting any plots).
  2. Include some of the plots in the examples. The analysis scripts automatically generate the plots, but if you are only looking at the docs, the plots would help to clarify the results.
wehs7661 commented 3 years ago

I've opened a PR (new branch: improve-documentation) and left all my thoughts in the description of the PR. A lot of them are just pretty minor things but maybe there is some room for discussion. Overall, I think the documentation is very clear and beginner-friendly.

ptmerz commented 3 years ago

The documentation improvements, including the switch to jupyter notebooks and the improvements by @wehs7661 have taken care of most of these points, so I will close this.