I wrote up some suggestions for making the setup instructions more clear, and implemented some of the suggestions in this Pull Request.
Below are the associated notes providing some rationale for the changes here:
The documentation could be improved for end users. And should be reviewed and re-written making sure that they work easily on all supported platforms. For example, ‘Anaconda prompt’ is only available on Windows. The equivalent on MacOS and Linux is a terminal with appropriate modifications to bashrc or zshrc made during the Anaconda installation.
The statement ‘this page is written for a generalist audience’ should be given context (why include this?) … is it because experts should feel free to skip Anaconda, but instructions for doing so are not included?
Installation instructions assume that the code is available on the computer. They should include the commands required e.g. git clone or conda install
When referring to repository root, don’t use a leading “/“ which implies the location is relative to the system root directory. i.e. “agweatherqaqc/env/environment.yml” instead of “/agweatherqaqc/env/environment.yml”
Here are some other places where users might get stuck:
“Once you’re done installing Anaconda, open the Anaconda prompt and type: condo info”
On macOS and Linux there is no anaconda prompt, just a terminal
Should be “open the Anaconda prompt (on Windows) or Terminal (MacOS or Linux)”
“Using the Anaconda prompt, navigate to the environment.yml file”
Again, the concept of anaconda prompt is specific to windows
Steps used to ‘Navigate to’ should be given (e.g. git clone …; cd agweatherqaqc/env; condo env …)
But, rather than navigate to, perhaps simpler to navigate to repository root and specify path in condo env command, e.g. conda env create -f agweatherqaqc/env/environment.yml
“And then follow the prompts. This will setup a new environment called “agweatherqaqc”, which can be activated by typing:
activate agweatherqaqc”
There is no command ‘activate’, perhaps only on the anaconda prompt? On MacOS it is ‘conda activate’
If by ‘follow the prompts’ you mean ‘conda activate’, you can just say ‘activate the conda environment using conda activate agweatherqaqc as instructed
Ultimately, the following commands or their equivalent should be provided in order to ensure users have all of the information required for setup:
While reviewing for JOSS https://github.com/openjournals/joss-reviews/issues/6368
I wrote up some suggestions for making the setup instructions more clear, and implemented some of the suggestions in this Pull Request.
Below are the associated notes providing some rationale for the changes here:
The documentation could be improved for end users. And should be reviewed and re-written making sure that they work easily on all supported platforms. For example, ‘Anaconda prompt’ is only available on Windows. The equivalent on MacOS and Linux is a terminal with appropriate modifications to bashrc or zshrc made during the Anaconda installation.
The statement ‘this page is written for a generalist audience’ should be given context (why include this?) … is it because experts should feel free to skip Anaconda, but instructions for doing so are not included?
Installation instructions assume that the code is available on the computer. They should include the commands required e.g. git clone or conda install
When referring to repository root, don’t use a leading “/“ which implies the location is relative to the system root directory. i.e. “agweatherqaqc/env/environment.yml” instead of “/agweatherqaqc/env/environment.yml”
Here are some other places where users might get stuck: “Once you’re done installing Anaconda, open the Anaconda prompt and type: condo info”
“Using the Anaconda prompt, navigate to the environment.yml file”
git clone …;cd agweatherqaqc/env;condo env …)conda env create -f agweatherqaqc/env/environment.yml“And then follow the prompts. This will setup a new environment called “agweatherqaqc”, which can be activated by typing:
Ultimately, the following commands or their equivalent should be provided in order to ensure users have all of the information required for setup:
Remove “After this, setup is complete. Once your input files are configured agweather-qaqc is ready to run.” Since it is covered in the next section.