Skip to content

Commit

Permalink
update README episode; closes #274, closes #279
Browse files Browse the repository at this point in the history
  • Loading branch information
@bast
bast committed Sep 23, 2023
1 parent 973873f commit f59055b
Show file tree
Hide file tree
Showing 2 changed files with 84 additions and 151 deletions.
2 changes: 2 additions & 0 deletions content/wishlist.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@
`README.rst` can be enough (more about these formats later).


(checklist)=

## Creating a checklist

```{discussion} Motivation-2: Create a wishlist
Expand Down
233 changes: 82 additions & 151 deletions content/writing-readme-files.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,180 +2,111 @@

# Writing good README files

```{questions}
- What should be included as a bare minimum in README files?
```

```{objectives}
- Write a README file according to good practices.
```

---

The `README` file (often `README.md` or `README.rst`) is usually the first
thing users/collaborators see when visiting your GitHub repository. Use it to
communicate important information about your project! For many
smaller or mid-size projects, this is enough documentation. It's not
that hard to make a basic one, and it's easy to expand as needed.


## Exercises

This lesson is exercise-based with some hints at the bottom.

```{instructor-note}
- Groups can choose to work on either exercise README-1, or on exercises README-2 + README-3.
- Exercise README-1 creates and discusses a README for an example Python project.
- Exercise README-2 can be interesting if learners already have a project/code of their own.
- Exercise README-3 (constructively) discusses READMEs of projects which you have recently used.
```

### Exercise: Basic readme

````{exercise} Exercise README-1: Write a README file for an example Python project
**The example project**
Here's [the example project](https://github.com/escience-academy/coderefinery-documentation-example-project).
For this project we transformed the code snippets from the previous episode into a single script [analyse_spreadsheet.py](https://github.com/escience-academy/coderefinery-documentation-example-project/blob/main/analyse_spreadsheet.py)
Let's take a look at [the script](https://github.com/escience-academy/coderefinery-documentation-example-project/blob/main/analyse_spreadsheet.py).
You don't need to understand the script completely, all you need to know is:
* The functions `mean_temperature` and `get_spreadsheet_columns` from previous episode are in there.
* We added a `main` function that is called when you run the script
(you could run this python script by calling `python analyse_spreadsheet.py` on the command line).
It will prompt the user for a file name, print the columns in the spreadsheet, and print the mean
temperature.
That's all there is to this project! (You can ignore the other files in the repository, we'll get back to them in episode 4)
**The exercise**
1. Fork the [the example project](https://github.com/escience-academy/coderefinery-documentation-example-project) to your own github namespace
2. Add a file called `README.md` (you can use the github web interface or work locally (i.e. `git clone`, edit the file, `git add`, `git commit`, `git push`))
3. Add some content to your README file. Think about what you want the audience to know about your project!
It does not matter whether the information is correct, it is more important that you have all the components that make up a good README file.
4. Note that the README file is nicely rendered on the github repository page.
5. Compare your README file with that of others, is all the essential information in there?
NB: The `README.md` file is written in 'Markdown' a very popular lightweight markup language, all you need to know for now is this syntax:
```markdown
# A section title
## A subsection title
Normal text
A list with items
- item1
- item2
```
(Optional): Use [https://hemingwayapp.com/](https://hemingwayapp.com/) to analyse your README file and make your writing bold and clear!
The README file (often `README.md` or `README.rst`) is usually the first thing
users/collaborators see when visiting your GitHub repository.

Use it to communicate important information about your project! For many
smaller or mid-size projects, this is enough documentation. It's not that hard
to make a basic one, and it's easy to expand as needed.


## Exercise: Have fun testing some README features

````{exercise} Exercise README-1: Have fun testing some README features you may not have heard about
- Test the effect of adding the following to your GitHub README ([read
more](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)):
```markdown
> [!NOTE]
> Highlights information that users should take into account, even when skimming.
> [!IMPORTANT]
> Crucial information necessary for users to succeed.
> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.
```
- For more detailed descriptions which you don't want to show by default you
might find this useful (please try it out):
```markdown
<details>
<summary>
Short summary
</summary>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
</details>
```
- Would you like to add a badge like this one: [![please replace with alt text](https://img.shields.io/badge/anytext-youlike-blue)](https://example.org)?
Badge that links to a website (see also <https://shields.io/>):
```markdown
[![please replace with alt text](https://img.shields.io/badge/anytext-youlike-blue)](https://example.org)
```
Badge without link:
```markdown
![please replace with alt text](https://img.shields.io/badge/anytext-youlike-blue)
```
- Know about other tips and tricks? Please share them with others.
````

`````{solution}
A README file for this project could look like this:
````markdown
# Temperature analysis in spreadsheets
A python script for the analysis of temperatures in excel files.
## Why should I use this project ?
It makes it easy to analyse excel files with temperatures in them.

## Exercise: Improve the README for your own project

## Setup
```{exercise} Exercise README-2: Draft or improve a README for one of your recent projects
Try to draft a brief README or review a README which you have written for one
of your projects.
You need `python>3.5` to run this script.
- You can do that either by screensharing and discussing or working individually.
The project depends on the `pandas` library, install it with pip:
`pip install pandas`
- Use the {ref}`checklist <checklist>` which we have discussed earlier.
- Think about the user (**which can be a future you**) of your project, what does this user need to know to use or
contribute to the project? And how do you make your project attractive to use or contribute to?
## How to run?
- (Optional): Try the [https://hemingwayapp.com/](https://hemingwayapp.com/) to analyse your README file and make your writing bold and clear.
You can run the script from the command-line using
- Please note observations and recommendations in the collaborative notes.
```
python analyse_spreadsheet.py
```
You can use functions directly, for example: calculate the mean temperature of some data:
```python
from analyse_spreadsheet import mean_temperature
print(mean_temperature(data))
```
## How to cite this project?
Please email `[email protected]` to get instructions on how to properly cite this project.
## Contributing
You are welcome to contribute to the code via pull requests. Please have a
look at the [NLeSC
guide](https://nlesc.gitbooks.io/guide/content/software/software_overview.html)
for guidelines about software development.
````
`````


### Exercise: Readme of your own project

```{exercise} Exercise README-2: Draft or review a README for one of your recent projects
Try to draft a brief README or review a README which you have written for one
of your projects.
You can do that either by screensharing and discussing or working individually.
Please note observations and recommendations in the collaborative notes.
```
---

### Exercise: Readme of another project
## Exercise: Discuss the README of a project that you use

```{exercise} Exercise README-3: Review and discuss a README of a project that you have used
In this exercise we will review and discuss a README of a project which you
have used. You can also review a library which is popular in your domain of
research and discuss their README.
You can do that either by screensharing and discussing or working individually.
- You can do that either by screensharing and discussing or working individually.
When discussing other people's projects please remember to be respectful and
constructive. The goal of this exercise is not to criticize other projects but
to learn from other projects and to collect the aspects that you enjoyed
finding in a README and to also collect aspects which you have searched for but
which are sometimes missing.
- When discussing other people's projects please remember to be respectful and
constructive. The goal of this exercise is not to criticize other projects but
to learn from other projects and to collect the aspects that you enjoyed
finding in a README and to also collect aspects which you have searched for but
which are sometimes missing.
Please note observations and recommendations in the collaborative notes.
- Please note observations and recommendations in the collaborative notes.
```

---

## Table of contents in README files

- GitHub generates a [TOC for README.md](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-readmes#auto-generated-table-of-contents-for-readme-files).
- On GitLab you can generate a TOC in Markdown with `[[_TOC_]]`.
- With RST you can generate a table of contents (TOC) automatically by adding `.. contents:: Table of Contents`.

---

## What makes up a good README file?

```{keypoints}
As a bare minimum a README file should include:
- A descriptive project title
- Motivation (why the project exists) and basics
- Installation / How to setup
- Copy-pastable quick start code example
- Usage reference (if not elsewhere)
- Recommended citation if someone uses it
- Other related tools ("see also")
```

```{callout} User experience
Think about the user (**which can be a future you**) of your project, what does this user need to know to use or
contribute to the project? And how do you make your project attractive to use or contribute to?
```
- GitHub automatically generates a [table of contents for README.md files](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-readmes#auto-generated-table-of-contents-for-readme-files).
- On GitLab you can generate a TOC in Markdown with:
```markdown
[[_TOC_]]
```
- With RST you can generate a table of contents (TOC) automatically by adding:
```rst
.. contents:: Table of Contents
```

0 comments on commit f59055b

Please sign in to comment.