We communicate with our collaborators

Most of research is done in teams

Good practices help teamwork, by:

• Keep track of what was (or was not) done
• Coordinate next steps
• Avoid work duplication

…but I work alone…

Even if we work alone, we are still communicating

• with your supervisor or advisor
• with the referees of your paper
• with other scientists that read (and cite) you
• with the next Ph.D. student in your lab
• with the general public
• with our future self

Each one of these interactions can improve following a good practice

Communicate with your supervisor

Research results are not enough

You must convince your boss (and the jury) that you deserve to be called “Doctor”

• Make your work easy to understand

• Make clear what is your original contribution

…with the referees of your paper

Referees are busy people who works for free

• Give them all they need to replicate and validate your work

• Being clear and transparent helps them to decide fast

You will get published faster
(or at least get good feedback)

…with other scientists in your field…

…that will read your paper (and hopefully cite it)

The game does not end when you publish

50% of papers are read only by the referee

• Make your work easy to understand and replicate

…with the general public

Eventually, your work will have an impact outside academia

(the end goal is to make a better world, no?)

We need to be aware of the ethical implications

• Access, licensing, copyright models
• Privacy concerning test subject
• Truth and academic integrity

…with your future self

Nothing is more frustrating that reading your old work

As they say: “The past is a foreign country”

Undocumented code/protocols are hard to understand…

and you can only blame yourself

Prepare your files for the next user

Someone unfamiliar with your project should be able to look at your computer files and understand in detail what you did and why

This “someone” could be

• someone who wants to try to reproduce your work,
• a collaborator who wants to understand your experiments,
• a future student in your lab extending your work
  • after you have moved on to a new job,
• your research advisor evaluating your research skills.

Most commonly, however, that “someone” is you.

Role of each folder

• docs is where you write your paper/talk/thesis
• data is anything that you get from outside the computer
• results is what your code produces
• code is where you write your code
• bib to store documents cited in your document
  • if it has a doi, it goes here
  • bibliographic database goes here
• extra for other documents without doi

Raw Data is Sacred

Producing data is expensive and time consuming

You don’t want to lose it. Mark it read only immediately
(and make backups)

Never modify raw data. Use a script to make a clean version

Use folders raw and clean inside data/YYYY-MM-DD
Code for that in scripts

Each folder needs a README file

Good filenames help a lot to understand the project

But they are usually not enough

A README file in each folder can explain the purpose of each file

It takes time to write them, but it saves time in the long run

What is a “project”?

We can distinguish four categories

• Projects with well-defined goals and deadlines, e.g. a thesis
• Areas that are permanently active, like “health” or “family”
• Resources that can be useful for several projects, like code libraries, or general interest papers
• Archives, anything that is no longer active. Can be copied to external media and stored out of the computer

Each one requires a separate folder

Spaces

Personally I like to group my Projects/Areas/Resources/ Archives by major topic

Be coherent when choosing filenames

Decide when to use ., -, and _

Avoid spaces in filenames

Either John-Smith.txt or John_Smith.txt

Usually . separates filetypes, like .csv or .yml

Examples

Bad Example

1-Introduction.docx
2_Methods.docx
3.Results.docx
4 discussion.docx
10-conclusions.docx
results-01-03-09.txt

Good Example

01-Introduction.docx
02-Methods.docx
03-Results.docx
04-Discussion.docx
10-conclusions.docx
2009-01-03-results.txt

Another Good Example

01_Introduction.docx
02_Methods.docx
03_Results.docx
04_Discussion.docx
10_conclusions.docx
20090103results.txt

Both are good, but use only one

Write dates as YYYY-MM-DD

• When was 8/3/1965? August or March?

• Is today 6/10/2023 or 10/6/2023?

It is better to write YYYY-MM-DD. This is an ISO standard

There is no ambiguity of meaning

Sorting alphabetically, numerically, and chronologically give the same result

Use an Online service

You can share your document via Dropbox or Google Drive

You can edit online using Microsoft Office 365 or Google Docs

Several people can work in the same document at the same time

Advantage: better spelling and grammar correction

But they require a permanent internet connection

Where to store it

• In the server only

• Cloud drive like Dropbox, Google Drive

  • Good to share large data and non-text files
  • Bad if two people changes the same file
  • Works better with permanent internet access

• Version control system like GitHub, GitLab, Bitbucket

  • Good for text and code, bad for big files
  • Keeps history
  • works well without internet access

Sharing

• Hybrid, using symbolic links

• Or use an online editor

  • Google Docs
  • HackMD.io
  • Overleaf