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
Not a stellar example, but I give Jesper from 5 years ago a pass.
Top comments (0)