View all pages

D - 1 Introduction to README files and Markdown in Life Science Research

Licenced under CC-BY 4.0 and OSI-approved licenses, see licensing.

Overview

Teaching: 15 min
Exercises: 45 min
Questions

  • What different kinds of READMEs are there?

  • What should you write in a README, based on the different kinds of READMEs?

  • What are the benefits of Markdown?

  • How do you write Markdown?

Objectives

  • Understand the purpose and importance of README files in research projects.

  • Learn the main sections to include in various types of READMEs.

  • Apply Markdown syntax to create and format README files.

Part 1: Understanding README files in Life Science Research

What is a README file?

A README file is usually a text file and serves as an introduction and guide to a project. Depending on its scope, a README might provide a project overview, explain the folder organization, or offer usage examples. It can also include details such as contribution guidelines and licensing information. Whether you are a researcher, PhD student, developer, or simply revisiting your own work, a good README simplifies navigating and using the project’s contents.

Why is the README important? A README helps team members and collaborators quickly understand the project, reducing the learning curve and improving efficiency. For software or datasets, a README provides necessary instructions on how to install, configure, and use the resources, making it easier for others to access your work.

What different kinds of README files are there?

First out is the project README which provides a general overview and how the data within the project is structured. This README should be put in the root folder of the project and it typically includes:

  • General information: A project title, scope and purpose, project members’ names, roles and contact info. It is also good practice to include a link to the Data management plan.
  • Organisation: Folder structure, file naming conventions, and file formats included in the project.
  • Usage: Information on how to use the project, including examples if applicable.
  • Study level README example Links to an external site. from RDMkit Links to an external site..

A data README is specific to datasets and includes information about the data. This README should be put in the subfolders of the data it describes and it usually covers:

A code README focuses on software or scripts. It provides information on how to run the code and includes:

Part 2: Introduction to Markdown

What is Markdown?

Markdown is a lightweight markup language with plain-text formatting syntax. It allows you to create formatted text using a plain-text editor. Markdown is different from an editor like Microsoft Word. In Word, you click buttons to format text and see the changes instantly (what you see is what you get). With Markdown, you add special syntax to your text to indicate formatting, but you won’t see the changes until you preview or render the file.

What are the benefits of Markdown?

  1. Markdown is a versatile language used for creating e.g. documents, emails, websites, and presentations.
  2. It is portable, allowing Markdown-formatted text to be opened with virtually any application, unlike proprietary formats like Microsoft Word.
  3. Markdown is platform-independent, enabling text creation on any device or operating system.
  4. It is future-proof, ensuring readability with any text editor even if the original application becomes obsolete.

Read more at www.markdownguide.org Links to an external site..

How do you write Markdown?

There are many online tools and editors available that let you live code your Markdown directly in the web browser, meaning you can see the formatted output as you type. If you want to try out live coding your Markdown, here are some examples:

  • markdownlivepreview.com Links to an external site. - a simple, web-based Markdown editor that provides a live preview of your Markdown text as you type.
  • dillinger.io Links to an external site. - is an online Markdown editor that also offers a live preview. Dillinger supports importing and exporting files from various sources like GitHub, Dropbox, and Google Drive, making it useful for more integrated workflows
  • stackedit.io Links to an external site. - is a more advanced, web-based Markdown editor that supports offline editing, synchronization with cloud services (Google Drive, Dropbox, GitHub). It also offers collaboration features, allowing multiple users to work on the same document simultaneously.

If you have Visual Studio Code (VS Code) Links to an external site. installed on your computer, you can open it and create a new text file. Select Markdown as the language and start typing. VS Code can also auto-detect the language, and it allows you to preview and render the output locally on your computer.

For an overview of the basic Markdown syntax, please go to markdownguide.org and its representation of the Markdown elements outlined in the original design document Links to an external site..

Part 3: Exercises

Welcome to the exercises section! These exercises are designed to help you practice creating and formatting README files using Markdown. If you want to begin with an interactive Markdown tutorial, you can visit Commonmark’s tutorial Links to an external site.. Otherwise, you can go directly to the exercises and come back for the tutorial at a later stage.

If this is the first time you write in Markdown, markdownlivepreview.com Links to an external site. could be a good choice to get started but you are free to use any other tool as well. For additional help and examples, make use of the Cheat Sheet Links to an external site. from markdownguide.com.

Exercise 1: Basic Structure

Task: Create a basic README file for a hypothetical project. Include sections for the project title and description.

Hint

Use headings for each section and try different levels. Do not forget a space after the #, and the blank lines before and after the headings.

Exercise 2: Detailed Project Information

Task: Expand the README file from Exercise 1 to include information about the project members, their roles, and contact information. Also, add a section for the project’s data management plan.

Hint

Include a table with the project members, their roles, and contact information. Add a link to the data management plan.

Exercise 3: Folder Structure and File Naming

Task: Add a section to your README file that describes the folder structure and file naming conventions used in your project. Use Markdown to create a visual representation of the folder hierarchy.

Hint

Use bullet points or code syntax to represent the folder structure and file naming conventions.

Exercise 4: Explore published READMEs on GitHub

Task: Go to the GitHub repository awesome-readme Links to an external site. and find an example README of your interest. Write down some features that you find useful and try to add them to your README from exercise 3, or create a new README.

Hint

Experiment with different Markdown elements to see how they affect the formatting. If you need examples you can take a look at the basic syntax Links to an external site. or the extended syntax Links to an external site. from the markdownguide.com Links to an external site..