I wish that this article had focused more on the "how to" aspect of this problem and less on the "what" part. It feels a little muddied between trying to explain the problem space (researchers re-using code) and the "steps" involved (write clear code + docs, use Git).
As somebody that runs a semi-popular Open Source project[0], I am very aware of the painstaking task of taking a "hacky script on my machine" and turning it into something public that others can not only use, but trust enough to _depend_ on too.
Here is a rough checklist of tasks that come to mind:
- Write a Readme with a description of what the project is (help Google index it for future search)
- Publish a Docker image that can build the whole project and produce a binary or run the server (this is a massive PITA to get setup -- once you do this, setting up CI becomes very easy)
- Ideally there is a Docker image with a small POC app too (which is often more useful that docs are imo)
- Put the project into Awesome Lists so that people will actually find it (also helps with SEO)
- Add a license to the repo and, if you really want people to trust it, add license headers to every file (I see _so many_ projects without even a LICENSE file. Without this, it's illegal to use the code at all!)
Beyond all of that, Docs help a lot too, as does a "legit" looking website, but you can get away with pretty crappy docs if you do all of the above.
Documentation, preferably including FAQ for bigger projects, is key. Saves time and energy for users/customers (current or potential), future maintainers, other developers and support teams.
Another recommendation: Limit your dependencies to what is strictly necessary.
> but you can get away with pretty crappy docs if you do all of the above
Depends on your audience, I suspect. When evaluating something for use, the first thing I look at are the docs. No docs, or just videos pretending to be documentation makes it super easy to skip and move on to the next possibility. Crappy docs means I only come back to it if everything else is worse.
It's not illegal perse but without a license file all rights are reserved to the owner per GitHub. So you could get sued and they'd (maybe) have a case.
I won't argue for a particular license, but you should have one. I personally won't touch a project without a license as I usually aim to monetize my work somehow and don't want a potential legal headache.
For example in Germany. Copyright applies automatically and you can't just use anything (images, code, text, and so on) without explicit okay by the producer of this.
A license just allows you to use the content/code under specific conditions.
As somebody that runs a semi-popular Open Source project[0], I am very aware of the painstaking task of taking a "hacky script on my machine" and turning it into something public that others can not only use, but trust enough to _depend_ on too.
Here is a rough checklist of tasks that come to mind:
- Write a Readme with a description of what the project is (help Google index it for future search)
- Publish a Docker image that can build the whole project and produce a binary or run the server (this is a massive PITA to get setup -- once you do this, setting up CI becomes very easy)
- Put the project into Awesome Lists so that people will actually find it (also helps with SEO)- Add a license to the repo and, if you really want people to trust it, add license headers to every file (I see _so many_ projects without even a LICENSE file. Without this, it's illegal to use the code at all!)
Beyond all of that, Docs help a lot too, as does a "legit" looking website, but you can get away with pretty crappy docs if you do all of the above.
0: https://github.com/lunasec-io/lunasec/