Add new sections and guidelines to root README template #143

georgerichardson · 2022-09-07T15:34:39Z

I have updated the project root README to provide a template and guidance for writing a useful and informative introduction to a project. The approach I have taken is quite verbose but has the advantage of providing the user with a substantial description of what might go in each section, which could be particularly useful for newer team members.

For inspiration, I have used the READMEs of:

I'm not completely settled on this approach - some quetsions I have are:

Should there be some instructions at the top for how to use the readme?
Is this too verbose? Would a better approach be to just have a checkbox list at the top with possible sections and one sentence on what to put in them. (This would be neater, but leaves more overhead for users and has a higher risk of just being ignored imo.)

closes #142
closes #139

lizgzil

looks great!

lizgzil · 2022-09-08T09:25:01Z

{{ cookiecutter.repo_name }}/README.md

+  - **_slide decks_**
+  - **_media_**
+
+![Maybe add an image or nice graphic relating to the project here. This one is by Alan Warburton / © BBC / Better Images of AI / Plant / CC-BY 4.0](https://betterimagesofai.org/ImagesAI/WarburtonNature_01_1280x720.jpg)


lizgzil · 2022-09-08T09:28:59Z

{{ cookiecutter.repo_name }}/README.md

+
+## 📂 Contents
+
+**_Write a high level outline of the repository contents and structure. What are the main functions and outputs and where can the reader find them? This is not a replacement for informative readmes in sub-directories!_**


Could add "This is not a replacement for informative readmes in sub-directories - which could also be linked to here."

lizgzil · 2022-09-08T09:39:33Z

{{ cookiecutter.repo_name }}/README.md

+
+**_Write a high level outline of the repository contents and structure. What are the main functions and outputs and where can the reader find them? This is not a replacement for informative readmes in sub-directories!_**
+
+## 🛠️ Setup and installation


This section and contributor guidelines section are kind of related (especially because of the github parts of the setup process), so perhaps shouldn't be separated out into two sections/should be next to each other?

lizgzil · 2022-09-08T09:39:57Z

{{ cookiecutter.repo_name }}/README.md

+
+Activate the newly created conda environment with `conda activate {{ cookiecutter.project_name }}`
+
+## 💾 Datasets


this is a good idea - I really benefitted from this recently with https://github.com/nestauk/mapping_parenting_tech

lizgzil · 2022-09-08T09:54:36Z

On your two questions

Should there be some instructions at the top for how to use the readme? I personally think it's self explanatory
Is this too verbose? Would a better approach be to just have a checkbox list at the top with possible sections and one sentence on what to put in them. (This would be neater, but leaves more overhead for users and has a higher risk of just being ignored imo.) I agree with the checkbox maybe getting ignored. I think this makes it really clear on what people need to fill in.

Jack-Vines · 2022-09-09T18:19:26Z

{{ cookiecutter.repo_name }}/README.md

+
+```
+$ mkdir .cookiecutter/state
+$ touch .cookiecutter/state/conda-create.log


having this here is a good shout

beingkk · 2022-09-23T10:25:03Z

{{ cookiecutter.repo_name }}/README.md

+$ touch .cookiecutter/state/conda-create.log
+```
+
+Run `make install` to configure the development environment:


Suggested change

Run `make install` to configure the development environment:

Run `make install` to configure the development environment. This will do the following:

For someone who does this for the first time, this might be quite cryptic - perhaps it's OK to be a bit more verbose throughout the setup steps.

beingkk · 2022-09-23T10:25:47Z

{{ cookiecutter.repo_name }}/README.md

+Run `make install` to configure the development environment:
+
+- Setup the conda environment
+- Configure `pre-commit`


Suggested change

- Configure `pre-commit`

- Configure `pre-commit` procedures (eg, automated code formatting before committing)

beingkk · 2022-09-23T10:26:26Z

{{ cookiecutter.repo_name }}/README.md

+
+Run `make install` to configure the development environment:
+
+- Setup the conda environment


Suggested change

- Setup the conda environment

- Setup the conda environment and install the required packages specified in `requirements.txt`

beingkk · 2022-09-23T10:27:04Z

{{ cookiecutter.repo_name }}/README.md

+
+**Step 3.** Install, configure and activate the environment for this project on your machine.
+
+Create a blank cookiecutter conda log file:


Perhaps can specify why this is useful?

beingkk · 2022-09-23T10:28:22Z

{{ cookiecutter.repo_name }}/README.md

+
+- [gh](https://formulae.brew.sh/formula/gh) - GitHub command line tool.
+- [direnv](https://formulae.brew.sh/formula/direnv#default) - For using environment variables.
+- [git-crypt](https://github.com/AGWA/git-crypt/blob/master/INSTALL.md#installing-on-mac-os-x) - Tool for encryption of sensitive files.


Suggested change

- [git-crypt](https://github.com/AGWA/git-crypt/blob/master/INSTALL.md#installing-on-mac-os-x) - Tool for encryption of sensitive files.

- [git-crypt](https://github.com/AGWA/git-crypt/blob/master/INSTALL.md#installing-on-mac-os-x) - Tool for encryption of sensitive files. Install this if you want to share sensitive information with your collaborators on GitHub (eg, passwords, API keys or data that can't be shared externally).

beingkk · 2022-09-23T10:30:05Z

{{ cookiecutter.repo_name }}/README.md

+**_Write a high level outline of the repository contents and structure. What are the main functions and outputs and where can the reader find them? This is not a replacement for informative readmes in sub-directories!_**
+
+## 🛠️ Setup and installation
+


Suggested change

**_Adapt this section according to your project's specific setup requirements. This template is indicative of the necessary steps for a "typical" Nesta project._**

beingkk · 2022-09-23T10:32:07Z

{{ cookiecutter.repo_name }}/README.md

+Install the following components:
+
+- [gh](https://formulae.brew.sh/formula/gh) - GitHub command line tool.
+- [direnv](https://formulae.brew.sh/formula/direnv#default) - For using environment variables.


Suggested change

- [direnv](https://formulae.brew.sh/formula/direnv#default) - For using environment variables.

- [direnv](https://formulae.brew.sh/formula/direnv#default) - For using environment variables (eg, the .env file, which we used to store global variables that can be accessed from any python script)

Not sure how to best explain, but perhaps useful to be a bit more verbose here?

beingkk

Hey @georgerichardson, apologies for the late review - I think it looks very good!

My only (optional) suggestion would be about that maybe the Setup steps can be a little bit more verbose - I think they are quite short at the moment, and might be a bit cryptic especially for someone who hasn't created a Nesta project before. Also, perhaps we can note that not everything has to be set up in exactly this way (eg, perhaps git-crypt is not always necessary).

I've added comments to that effect in the readme file.

Hope this helps!

georgerichardson added 3 commits September 7, 2022 16:11

Change to include more sections and guidance to complete

1c04ddc

Add instructions for logfiles

503aee2

Fix image attribution

a6cc58d

georgerichardson requested review from mindrones, lizgzil, beingkk and Jack-Vines September 7, 2022 15:34

Update for prettier approval

9f2e840

lizgzil approved these changes Sep 8, 2022

View reviewed changes

Jack-Vines approved these changes Sep 9, 2022

View reviewed changes

beingkk reviewed Sep 23, 2022

View reviewed changes

beingkk approved these changes Sep 23, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add new sections and guidelines to root README template #143

Add new sections and guidelines to root README template #143

georgerichardson commented Sep 7, 2022

lizgzil left a comment

lizgzil Sep 8, 2022

lizgzil Sep 8, 2022

lizgzil Sep 8, 2022

lizgzil Sep 8, 2022

lizgzil commented Sep 8, 2022

Jack-Vines Sep 9, 2022

beingkk Sep 23, 2022

beingkk Sep 23, 2022

beingkk Sep 23, 2022 •

edited

Loading

beingkk Sep 23, 2022

beingkk Sep 23, 2022 •

edited

Loading

beingkk Sep 23, 2022 •

edited

Loading

beingkk Sep 23, 2022

beingkk left a comment


		## 📂 Contents

		_Write a high level outline of the repository contents and structure. What are the main functions and outputs and where can the reader find them? This is not a replacement for informative readmes in sub-directories!_


		_Write a high level outline of the repository contents and structure. What are the main functions and outputs and where can the reader find them? This is not a replacement for informative readmes in sub-directories!_

		## 🛠️ Setup and installation


		Activate the newly created conda environment with `conda activate {{ cookiecutter.project_name }}`

		## 💾 Datasets

	Run `make install` to configure the development environment:
	Run `make install` to configure the development environment. This will do the following:

	- Configure `pre-commit`
	- Configure `pre-commit` procedures (eg, automated code formatting before committing)


		Run `make install` to configure the development environment:

		- Setup the conda environment

	- Setup the conda environment
	- Setup the conda environment and install the required packages specified in `requirements.txt`


		Step 3. Install, configure and activate the environment for this project on your machine.

		Create a blank cookiecutter conda log file:

	- [git-crypt](https://github.com/AGWA/git-crypt/blob/master/INSTALL.md#installing-on-mac-os-x) - Tool for encryption of sensitive files.
	- [git-crypt](https://github.com/AGWA/git-crypt/blob/master/INSTALL.md#installing-on-mac-os-x) - Tool for encryption of sensitive files. Install this if you want to share sensitive information with your collaborators on GitHub (eg, passwords, API keys or data that can't be shared externally).


	_Adapt this section according to your project's specific setup requirements. This template is indicative of the necessary steps for a "typical" Nesta project._

	- [direnv](https://formulae.brew.sh/formula/direnv#default) - For using environment variables.
	- [direnv](https://formulae.brew.sh/formula/direnv#default) - For using environment variables (eg, the .env file, which we used to store global variables that can be accessed from any python script)

Add new sections and guidelines to root README template #143

Are you sure you want to change the base?

Add new sections and guidelines to root README template #143

Conversation

georgerichardson commented Sep 7, 2022

lizgzil left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lizgzil commented Sep 8, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

beingkk Sep 23, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

beingkk Sep 23, 2022 • edited Loading

Choose a reason for hiding this comment

beingkk Sep 23, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

beingkk left a comment

Choose a reason for hiding this comment

beingkk Sep 23, 2022 •

edited

Loading

beingkk Sep 23, 2022 •

edited

Loading

beingkk Sep 23, 2022 •

edited

Loading