Skip to content

LMN README File Convention

When to use a README?

README.txt files should go into each folder which contain files that need to be explained. One can for example describe the project itself, the project structure/file naming or the state/content of the files.

At the LMN we differentiate between three types of README files:

1. The project README file at the top folder

2. The content README file at the lower levels

3. The software README files at any level with codes or software

How to write a README

A README file is normally written using Markdown and is often saved as a .txt or a .md file.

1. The project README

The project README file contains all relevant informations needed to understand the project and data. Similarly to the cover page of a paper it will contain the infos to get a broad overview

It should include:

  1. A title (with #)

  2. Abstract (with ##, same for all following)

  3. Contributors

Here a list of the people involved in the project as well as their contacts/affiliations

  1. Data

  2. Where are the original data located? If they are not made publicly available add something like:

The original data to the study have not been made publicly available due to data protection laws. Please contact the authors directly if you are interested in the data.

  • Where are the preprocessed data? Which format are they stored?

  • Project Overview Here you might describe briefly:

  • Where did you measure?
  • What did you measure?
  • When did you measure?
  • Did you preregister? If yes, add link.
  • How many people did you measure?
  • How many did you exclude?
  • Which program did you use to design your paradigma?
  • What was the task?

  • What programm did you use for preprocessing/analysis? Also add version number.

  • Notes Any additional information important to reconstruct the experiment

2. The content README

All subfolders of your project can/should also include a README file. They are important for tracking last changes and explaining in more detail the folder content.

  1. A title (with #)

  2. Description

  3. What project process is located here? Paradigma, preprocessing, first-level,...?
  4. Describe the process in detail.
  5. Additionally, you can add rationale for each process (answer why). Or
  6. What kind of files are available in the folder?
  7. How were they produced?
  8. Who was involved in producing them?

  9. What are the next procedures?

  10. Software

  11. What software is used for working with the files?
  12. Which version is used?

  13. Is it open source or not?

  14. Folder Structure Describe Folder content, file naming convention. What is there and how many?

  15. Notes Any more TODOs and important updates can be added here.

3. The software README

If you have developed a new software or code then you can add a README file directly under the main folder. It includes:

  1. A title (with #)

  2. Overview For what is the software/code useful? Explain its function.

  3. Installation/Run procedure

  4. Dependencies Which programming languages are needed? Which packages/functions? Add links to these sites.

  5. Folder structure and Files Please describe which folder structure includes which aspect of the project. Where are relevant functions stored? And what do the single files do?

  6. Contributors/Credits Here a list of the people involved in the project as well as their contacts/affiliations. Add what has been done by whom.

  7. Licence Decide whether you want to make it open source or not.

At the bottom of the page add:

Last updated on .... by ...