From bb0bc6aba839fef1b47db04416a2ad46f7df58b7 Mon Sep 17 00:00:00 2001 From: Joe Heffer Date: Fri, 19 Jul 2024 16:12:12 +0100 Subject: [PATCH 1/7] Add an exercise to create a readme file --- episodes/readmes.md | 47 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/episodes/readmes.md b/episodes/readmes.md index fdae945..0c84541 100644 --- a/episodes/readmes.md +++ b/episodes/readmes.md @@ -38,12 +38,53 @@ Let's create a new code project. Create a new, empty directory to contain your w ::::::::::::::::: solution +Follow these general steps to create a README file. +The specific details for each operating system are detailed below. + +1. Create a directory to contain your project. We call this the _root directory_; +2. In that directory, create a new text file; +3. Name the file `README.txt`; +4. Open the file for editing—start writing your documentation! + +::: group-tab + +### Windows + +1. Open [File Explorer](https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1) to browse the file system; +2. In a folder, right click and select New → Folder; +3. Name the folder `oddsong`; +4. Open that new folder, then right click and select New → Text Document; +5. Name the file `README.txt`; +6. Double-click on the file to open it for editing. + +### Linux + +Use the [File Manager](https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en) to create a new directory called `oddsong`. Inside that folder, create a new text file called `README.txt`. + +These steps may be achieved using the terminal as follows: + ```bash -mkdir my_project -touch my_project/README.txt -echo "This is my code" >> my_project/README.txt +mkdir oddsong +touch oddsong/README.txt +echo "This is my code" >> my_project/oddsong.txt +nano oddsong/README.txt ``` +### MacOS + +Use the [Finder](https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac) file manager to create a new directory called `oddsong`. Inside that folder, create a new text file called `README.txt`. + +These steps may be achieved using the terminal as follows: + +```bash +mkdir oddsong +touch oddsong/README.txt +echo "This is my code" >> my_project/oddsong.txt +nano oddsong/README.txt +``` + +::: + :::::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::::::::::: From 3a262218cf6fd021817516ace0aa8e6614043e36 Mon Sep 17 00:00:00 2001 From: Joe Heffer Date: Fri, 19 Jul 2024 16:19:34 +0100 Subject: [PATCH 2/7] Add exercise to rename the file --- episodes/readmes.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/episodes/readmes.md b/episodes/readmes.md index 0c84541..2adc2bb 100644 --- a/episodes/readmes.md +++ b/episodes/readmes.md @@ -124,6 +124,50 @@ Most people prefer to use a file format that allows you to create headers to org In this case, a Markdown document may be used. Markdown is a simple mark-up language that allows you to format your text using symbols to represent headers, bold text, bullet lists, etc. that are displayed to the user in an appealing way. The Markdown syntax will be converted into appealing visual styles that make your documentation more aesthetically pleasing and easier to read. +::::::::::::::::::::::::::::::::: challenge + +Convert your README file to Markdown format to enable more advanced formatting options. + +::::::::::::::::: solution + +Follow these steps to rename `README.txt` to `README.md`. + +::: group-tab + +### Windows + +Use [File Explorer](https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1) to [rename the file](https://support.microsoft.com/en-gb/office/rename-a-file-baea7aab-760b-4ee0-af58-06e940d505a4) from `README.txt` to `README.md`. + +1. Open the `oddsong` directory; +2. Right-click on `README.txt` and select "Rename"; +3. Type `README.md`. + +### Linux + +Use the [File Manager](https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en) to [rename the file](https://help.ubuntu.com/stable/ubuntu-help/files-rename.html.en) from `README.txt` to `README.md`. + +This step may be achieved using the terminal as follows: + +```bash +mv README.txt README.md +``` + +### MacOS + +Use the [Finder](https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac) to [rename the file](https://support.apple.com/en-gb/guide/mac-help/mchlp1144/mac) from `README.txt` to `README.md`. + +This step may be achieved using the terminal as follows: + +```bash +mv README.txt README.md +``` + +::: + +:::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::::: + An example README file in Markdown format is shown below, in a file called `README.md` where .md is the file extension for Markdown files. ### Section headers From d481396594d850fe4800dae29aee27e1d59102a3 Mon Sep 17 00:00:00 2001 From: Joe Heffer Date: Fri, 19 Jul 2024 16:29:00 +0100 Subject: [PATCH 3/7] Add a challenge to consider installation requirements --- episodes/readmes.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/episodes/readmes.md b/episodes/readmes.md index 2adc2bb..8613aab 100644 --- a/episodes/readmes.md +++ b/episodes/readmes.md @@ -104,6 +104,20 @@ For research code, it’s often important to explain the context in which the so Provide instructions for installing your research software. These steps should be laid out in simple, clear language and organised in a step-by-step manner. +::: challenge + +Consider a research code project you've worked on. +Discuss the technical prerequisites for that software or system. +What would someone need to do, when starting from a blank slate, to recreate that environment? + +Think about: + +- What hardware and software did you need? +- What drivers and libraries were required? +- What software setup, calibration, and configuration is required? + +::: + For most research code, the user will need to install the programming language onto their computer, such as R or Python, so it’s useful to link to the download pages and provide a link to the package manager tools that are commonly used in those ecosystems. This might also include listing any prerequisites such as hardware or software that must be installed first, such as device drivers. Consider how the installation method might differ for users of other common operating systems, such as Windows, Linux, and Mac OS. From 60061897bfb87e026b07ef4008a6920f67244f38 Mon Sep 17 00:00:00 2001 From: Joe Heffer Date: Fri, 19 Jul 2024 16:33:08 +0100 Subject: [PATCH 4/7] Add assumptions callout --- episodes/readmes.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/episodes/readmes.md b/episodes/readmes.md index 8613aab..e7c8bdb 100644 --- a/episodes/readmes.md +++ b/episodes/readmes.md @@ -98,6 +98,15 @@ The essentials contents of a README file are: It can be useful to signpost to other, related useful software tools by providing links and explaining how other software is related or different to this project when it comes to addressing these kinds of research problems. +::: callout + +Put yourself in the shoes of a researcher who has encountered your software for the first time. +Consider, if you had to start from square one, how would you like the code to be introduced to you? +Remember: things that are obvious to you and your colleagues may not be clear to others. +What assumed knowledge must you explicitly explain to get them up to speed? + +::: + For research code, it’s often important to explain the context in which the software was written and the theory behind it. For example, many researchers write analysis packages or workflows that are based on previously-published research, statistical methods, or theoretical models for which citations can be provided. By including references to research papers we better help the users to understand the methods that are implemented by our software, which enables its users to properly cite their sources and increases the users’ confidence that you have applied those methods correctly. ### Installation instructions From 6a6653d0677c6d4aae2fdece66010a6c1d1cea0a Mon Sep 17 00:00:00 2001 From: Joe Heffer Date: Fri, 19 Jul 2024 16:39:47 +0100 Subject: [PATCH 5/7] Add user guide content --- episodes/readmes.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/episodes/readmes.md b/episodes/readmes.md index e7c8bdb..acc4b64 100644 --- a/episodes/readmes.md +++ b/episodes/readmes.md @@ -137,10 +137,23 @@ All software should include some short guidance on how to use it and what the ma Many users will benefit from a frequently asked questions (FAQ) or troubleshooting notes, which describes common error messages, explains why they occur, and the steps to resolve them. +::: callout + The writing style should be concise, jargon-free, clear, and pitched at the appropriate level to the intended target audience. All technical terms and acronyms should be explained. However, don’t reinvent the wheel by defining all the terms used, instead link to a reliable external source or journal article. +::: + Diagrams can be particularly useful to explain complex concepts and workflows. Screenshots may also provide a visual demonstration of how the software will work. +::::::::::::::::::::::::::::::::: challenge + +Discuss with the group: + +- Reflecting on your past experiences, what software or systems have you used that included excellent diagrams and illustrations to help you learn to use them as a new user? +- Have you ever watched a tutorial video online that explained a software tool or process? What did you like and dislike about the walkthrough? + +::::::::::::::::::::::::::::::::: + ## Markdown format Most people prefer to use a file format that allows you to create headers to organise the content into sections or chapters, which is much clearer for the reader. From bc44fc9925464b844ad31de9412587e78155acd0 Mon Sep 17 00:00:00 2001 From: Joe Heffer Date: Fri, 19 Jul 2024 16:47:37 +0100 Subject: [PATCH 6/7] Add exercises on readme structure --- episodes/readmes.md | 63 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 61 insertions(+), 2 deletions(-) diff --git a/episodes/readmes.md b/episodes/readmes.md index acc4b64..cc75f56 100644 --- a/episodes/readmes.md +++ b/episodes/readmes.md @@ -211,9 +211,9 @@ An example README file in Markdown format is shown below, in a file called `READ You can separate your document into hierarchical sections with headings using the `#` symbol. This makes your README easier to navigate. For example: ```markdown -# My research software +# Birdsong identification tool -This software is designed to... +This user guide provides instructions on how to use this birdsong identifier. The software is designed to assist users in identifying bird species based on their vocalisations. # Installation @@ -226,6 +226,65 @@ To use this package... The “#” symbol means that line will be converted into a header and displayed to the reader in a large, bold font. This makes it easier for the reader to find the part of your text they're looking for, just like having chapters in a book. +::::::::::::::::::::::::::::::::: challenge + +Create suitable headers in your document. + +How would you organise your document by dividing up the text into subsections by adding further subheadings? + +::::::::::::::::: solution + +We can create the commonly-used headers used in READMEs by using the Markdown syntax shown below + +```markdown +# Title + +Brief introduction to the tool... + +# Installation + +To get started... + +# Usage + +To use this tool... +``` + +This gives some basic structure to the document, which we'll flesh out later. + +We can further subdivide the content by using _header levels_ + +```markdown +# Title + +Brief introduction to the tool... + +# Installation + +To get started... + +## Prerequisites +... + +## Drivers +... + +# Usage + +To use this tool... + +## Quick start +... + +## Examples +... +``` + + +::::::::::::::::: + +::::::::::::::::::::::::::::::::: + If your code is published on GitHub, the home page of your code repository will display the README.md file, including a navigation menu that is automatically created to easily select the section of the document to view. !["This repository has a README file with chapters, making navigation easier."](fig/bootstrap-readme-chapters.png){alt="A screenshot of a GitHub repository with a drop-down navigation menu on the readme text box."} From c43e15c8d8cf54d806ee2bbc94478b65f9618ea4 Mon Sep 17 00:00:00 2001 From: Joe Heffer Date: Fri, 19 Jul 2024 16:49:26 +0100 Subject: [PATCH 7/7] Explain markdown subheaders --- episodes/readmes.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/episodes/readmes.md b/episodes/readmes.md index cc75f56..356507d 100644 --- a/episodes/readmes.md +++ b/episodes/readmes.md @@ -252,7 +252,7 @@ To use this tool... This gives some basic structure to the document, which we'll flesh out later. -We can further subdivide the content by using _header levels_ +We can further subdivide the content by using _header levels_, where each subheading uses an additional `#` symbol. For example, `#` is a top-level heading, `##` is a section header, `###` is a subsection header, etc. ```markdown # Title @@ -280,6 +280,7 @@ To use this tool... ... ``` +These subheadings help the users to navigate the document. :::::::::::::::::