4 ms·

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 explai

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. 0: https://github.com/lunasec-io/lunasec/ https://github.com/lunasec-io/lunasec/

_jal 4y ago
> 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.
huepfebein 4y ago
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.
TedDoesntTalk 4y ago
> I see _so many_ projects without even a LICENSE file. Without this, it's illegal to use the code at all!) In what jurisdiction or country?
- sdoering 4y ago
  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. Else you just are not allowed to use it.
- ianbutler 4y ago
  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.
- Loranubi 4y ago
  AFAIK in at least some countries it's enough to mention the license somewhere. It's not necessary to include a full license file.

_jal 4y ago

> 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.

huepfebein 4y ago

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.

TedDoesntTalk 4y ago

> I see _so many_ projects without even a LICENSE file. Without this, it's illegal to use the code at all!) In what jurisdiction or country?

sdoering 4y ago
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. Else you just are not allowed to use it.
ianbutler 4y ago
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.
Loranubi 4y ago
AFAIK in at least some countries it's enough to mention the license somewhere. It's not necessary to include a full license file.