Skip to content

Specify the requisites for the example in the README #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ziotom78 opened this issue Oct 29, 2019 · 1 comment
Closed

Specify the requisites for the example in the README #4

ziotom78 opened this issue Oct 29, 2019 · 1 comment

Comments

@ziotom78
Copy link

Ideally, examples in a README should be self-contained and easy to run. The example provided in the README has the following problems:

  • It requires the user to run pip install getdist, but this is not stated clearly
  • It requires the user to create two directories, ../text_output/ and ../image_output/

None of these actions is too difficult for users with average experience, but it might lead people evaluating your software running away from it. Often people run examples before having completed reading the documentation.

Possible ways to solve the two points above:

  • Clearly state that the user should install getdist before trying the example, and provide the pip command to do so
  • Insert a call to `os.mkdir' in the example, so that you are sure the paths are always present. You should check if the path already exists, because people are likely to re-run the same example over and over again, changing the parameters to check how this affects the result.

(This issue is related to the ongoing review of this package for JOSS.)

@SuperKam91
Copy link
Owner

@ziotom78 thank you for your suggestions. I have added a few sentences detailing the getdist installation at the beginning of the example. I have also added a few lines of code to check for the mentioned directories, and create them if they don't exist

@ziotom78 ziotom78 closed this as completed Nov 2, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants