Closes issue #189 - README.md

[razman786]

Closes issue #189:

• Added Contents
• Added Introduction
• Added link to CONTRIBUTING.md file
• Added anchor links
• Updated layout
• Added Virtualenv install instructions
• Added user based install instructions
• Updated unit test install instructions
• Updated Python dependency section
• Added bug and feature request section

The README.md file updates will need to be reviewed by the project to ensure that it is in-line with its user base.

[texadactyl]

Some feedback for whatever it is worth:

• Please don't ever advise people to install from pypi.org as it is always lagging behind. So, don't do this: python3 -m pip install blimpy with or without --user. People should always "Install the latest release from the repository". That is currently what README.md states (imperfect file today but it is simple).
• I do not see the point of mentioning a --user parameter since by default, this is what will happen if you are not user ID 0 (I wish that I had removed all references to sudo before!). But, if you think that --user is relevant, you had better explain why since most of blimpy's users are scientists and some of them are significantly challenged by Linux/Unix.
• What you called a "Developer release" is really an installation operation for someone who is intending to modify the source code or run the regression tests - not many people. The word "developer" could also be someone who is just intending to use the packages and classes while developing their own application. Please change the language.
• "Install using PyPI" is a misnomer. What you are showing is how to install from github.
• "Unit tests" - should be identical to "Developer release". This section is redundant.
• "Using blimpy inside Docker" - You should not be referencing any user private space (FX196). That image is probably not up to date with the current github version of blimpy. If you wish to explain how people can build a docker image from github, please do so (see Dockerfile that we use for Github Actions which could be a starter kit).

Please keep it simple. Don't expect scientists to be fluent in Linux, docker, venv, etc. Note that several of them are MacOS users.

[razman786]

Thank you for the feedback. Comments are in-line below:

-------- Original Message -------- From: Richard Elkins @.*** Sent: Wednesday, 17 March 2021, 19:40 To: UCBerkeleySETI/blimpy Cc: Raz; Author Subject: [UCBerkeleySETI/blimpy] Closes issue #189 - README.md (#190)

Some feedback for whatever it is worth:

• Please don't ever advise people to install from pypi.org as it is always lagging behind. So, don't do this: |python3 -m pip install blimpy| with or without |--user|. People should always "Install the latest release from the repository". That is currently what README.md states (imperfect file today but it is simple).

No problem - default install using the repo only.

• I do not see the point of mentioning a |--user| parameter since by default, this is what will happen if you are not user ID 0 (I wish that I had removed all references to |sudo| before!). But, if you think that |--user| is relevant, you had better explain why since most of blimpy's users are scientists and some of them are significantly challenged by Linux/Unix.

Will simplify the README file.

• What you called a "Developer release" is really an installation operation for someone who is intending to modify the source code or run the regression tests - not many people. The word "developer" could also be someone who is just intending to use the packages and classes while developing their own application. Please change the language.

If there are not many people that will be developing, then I would look to split the developer information into a file of its own. Please let me know if there are any objections to this idea?

• "Install using PyPI" is a misnomer. What you are showing is how to install from github.

Point taken.

• "Unit tests" - should be identical to "Developer release". This section is redundant.

Will look to move such items into a developer file, as stated above.

• "Using blimpy inside Docker" - You should not be referencing any user private space (FX196). That image is probably not up to date with the current github version of blimpy. If you wish to explain how people can build a docker image from github, please do so (see |Dockerfile| that we use for Github Actions which could be a starter kit).

I will look into this - the updated README reused the original instructions.

Please keep it simple. Don't expect scientists to be fluent in Linux, docker, venv, etc. Note that several of them are MacOS users.

Point taken and I didn't know that some will be MacOS users. Scientists have normally surprised me how well they know their OS/code on a number of occasions.

Will send through an updated PR when ready.

Cheers,

Raz

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/UCBerkeleySETI/blimpy/pull/190#issuecomment-801358226, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABWJMGHLHIPNKB2Y4SQP5ATTEEATTANCNFSM4ZLBTMTA.

[texadactyl]

@razman786 Sorry but the source of the PR is 102 commits behind. Going to close.