DEV Community

Jesper Dramsch
Jesper Dramsch

Posted on • Originally published at dramsch.net on

My first first-author paper broke 50 citations. I think I know why and you can do it too

My first first-author paper broke 50 citations. I think I know why and you can do it too.

I shared my code and made it ridiculously easy to use.

I'm lazy myself.

If I find a paper that gives me all its ingredients ready to go,

I'm happy.

But how do you do this?

4ī¸âƒŖ There are four essential files in the repo:

  • License file - tell people how they're allowed to use it
  • conda_env.yml - tell people how to install
  • Readme - Document everything!
  • Jupyter NB - The actual code (with inline documentation)

đŸ’ŧŠī¸â„ĸī¸ How do you choose a license for your files?

I like choosealicense.com

Personally, I often go with the MIT license. It's easy, it removes your liability, it gives people the right to use and modify your code.

Modification means new research. That means citations!

🤖 Install Stuff.

It's great to provide a requirements.txt for pip

and/or

a conda_env.yml for conda installation.

I made it terribly hard for people and didn't provide package versions. Rookie mistake.

Step it one up and use poetry for exact reproduction of environments!

📝 Write that Readme.md

The readme file magically goes to the forefront of your @github repo.

Do the minimum, tell folks:

  • What is this about
  • How to install
  • How to use (files, commands, etc)
  • How to CITE! Put a bibtex file for extra credit.

🤷 People love to hate Jupyter Notebooks

But here's the thing.

Jupyter Notebooks are great, if you clean them before publication.

Put stuff into neat functions, organize sections, and make some nice plots.

Above all, use Markdown cells for inline documentation!

🏆 For extra credit:

đŸŗ Use docker to completely freeze the computational environment

🧮 Register your code on zenodo to give it a DOI

📌 Pin the repo to your github profile

Conclusion

  • Choose the right license for your code
  • Write amazing documentation
  • Make it easy to install, read, and use
  • Consider making it incredibly easy to use

Here's my repo.

Not a stellar example, but I give Jesper from 5 years ago a pass.

Top comments (0)