More explicit documentation

[ljvmiranda921]

• [x] Clarify the statement of need, explain what a "high-level interface" is in README.rst, ReadTheDocs, and Paper.md
• [x] I think it would be better to explicitly acknowledge the v.0.1.7 committers aside from the README.rst, and their respective Issues and PRs in the Changelog. And if possible, in the Paper.md

[ljvmiranda921]

Reference: openjournals/joss-reviews#433

[stsievert]

57 adds this sentence:

This means that instead of writing an optimizer from scratch, one just needs to supply the necessary PSO parameters, and let PySwarms do the rest of the procedure.

Is PySwarms composed of classes or functions? Here's a suggestion

PySwarms allows both performing basic optimizations with PSO and interacting with PSO optimizations. Interaction is enabled because PySwarms provides object primitives required for PSO optimization. This makes PySwarms useful for researchers or students.

I'm sure this needs more edits.

[ljvmiranda921]

Hi @stsievert , I like your suggestion. Do you mean that I change

It is intended for swarm intelligence researchers, practitioners, and students who would like a high-level interface of implementing PSO in their problems. This means that instead of writing an optimizer from scratch, one just needs to supply the necessary PSO parameters, and let PySwarms do the rest of the procedure.

Into this?

PySwarms allows both performing basic optimizations with PSO and interacting with PSO optimizations. Interaction is enabled because PySwarms provides object primitives required for PSO optimization. This makes PySwarms useful for researchers or students.

Just a small edit for flow, how about something like [...?]:

It is intended for swarm intelligence researchers, practitioners, and students who would like a high-level interface of implementing PSO in their problems. PySwarms both allows basic optimization with PSO and interaction with swarm optimizations. Interaction is enabled due to object primitives provided by the package for optimization. This makes PySwarms useful for researchers or students.

I just modified "PSO optimization", because it might read a little awkward if "PSO optimization" = "particle swarm optimization optimization"

Thank you so much for your suggestion and help 👍

[stsievert]

and students who would like a high-level interface of implementing PSO

Small wording suggestion: maybe change "high-level interface" to "declarative interface"? Or maybe "high-level declarative interface"?

a small edit for flow

Yup, looks good!

"PSO optimization" ... "particle swarm optimization optimization"

Yeah, I wondering about that as I was typing.

[ljvmiranda921]

Awesome! Okay, so it becomes

It is intended for swarm intelligence researchers, practitioners, and students who would like a high-level declarative interface of implementing PSO in their problems. PySwarms both allows basic optimization with PSO and interaction with swarm optimizations. Interaction is enabled due to object primitives provided by the package for optimization. This makes PySwarms useful for researchers or students.

If this is good then I'll change both README.rst and paper.md

[stsievert]

This looks good to me!

[stsievert]

Will README.rst also update the docs? I'd like to see an update to the docs too.

[ljvmiranda921]

Hi @stsievert , I didn't link README.rst with the docs so I edited them separately. Either way, the docs, README, and the Paper has been updated by commit fd00cc8582aeee370325c74b40b05ad313f3113a 😄