7 ms·
This applies to websites of open source projects, too. I remember when I visited docker.com for the first time because someone told me it's the latest shit and
by majewsky 9y ago
This applies to websites of open source projects, too. I remember when I visited docker.com for the first time because someone told me it's the latest shit and I just wanted to know what it is about. I browsed their website for 10 minutes, and summarized the experience to a coworker like this: "As far as I can see, it's the best thing ever and I'd be stupid not to use it, but I still does not know what it actually does."
Since then, whenever I make a website (or a README.md) for my open-source projects, I always make sure that it starts with
1. a short description of what the project is/does in one or two sentences, and
2. a longer explanation of the how and why in one or two paragraphs.
Representative example: https://github.com/sapcc/limes/tree/master/README.md https://github.com/sapcc/limes/tree/master/README.md
- TallGuyShort 9y agoFavorite conference quote ever: "So other than unicorns barfing rainbows, what is Docker?"
- PascLeRasc 9y agoThank you. I'm a hardware guy and I've heard about a dozen of explanations of what Docker is and even tried to set it up on my NAS but I still have no idea. And to the person about to comment with your version, I don't really care to know.
- ythn 9y agoDocker is building, running, and sharing VMs from the command line.
- wonderous 9y agoContainers are not VMs (virtual machines): https://blog.docker.com/2016/03/containers-are-not-vms/ https://blog.docker.com/2016/03/containers-are-not-vms/
- PascLeRasc 9y agoThank you for illustrating my point.
- fossuser 9y agoI don't understand why people don't frame the explanation in the context of what problem the thing is trying to solve. Imagine you have to install a database (let's say postgres) on your machine. You could just install it the regular way - when you do this postgres uses certain things by default like the port 5432. Now you're going to install a different piece of software on the machine, but this software also uses port 5432 by default and there's an error about the port already being in use. This is a pain, now you have to change the default port. It turns out these conflicts are happening for a lot of things on the machine and it's a hassle to have to make non-standard changes all over the place that you have to keep track of. For your first attempt to solve this you decide to run postgres in a virtual machine and connect to that, but now you have an entire extra operating system to deal with and all of the overhead that comes with that. Plus you have to configure access to the VM and get all of those pieces to work too. It'd be nice if there was a way to just install postgres in a place that is easily accessible, but separate from the rest of your machine with regard to things like ports and such. A "container" that it could be installed in that automatically handles things like port conflicts in some magical backend you don't have to deal with so it looks to you like you can always just use the defaults. This container model is basically docker (or at least my current understanding of it).
- PascLeRasc 9y agoHuh? What's a port? How do I "install a database"? I already have Excel on my laptop anyway. You lost me at around the third sentence.
- caseymarquis 9y agoYou may not be the target audience. Docker is a tool primarily used to help efficiently deploy your networked applications on new servers. If you don't need to deploy server apps, you can stop reading here. If you do need to deploy apps to servers, docker is worth investigating. It replaces a complex install script and git clones with an efficient clone of a lightweight 'vm' which is ready to run your app immediately.
- dogweather 9y agoYou’re describing Vagrant
- j_s 9y agoA discussion on "how a contributor can get the attention of a maintainer" touched on this briefly two weeks ago: · How to get an open source community to be interested in helping you | https://news.ycombinator.com/item?id=15538112 https://news.ycombinator.com/item?id=15538112 (2017Oct:140points,45comments) And a checklist for the reverse, as you discuss: · https://twitter.com/sehurlburt/status/921921604140937216 https://twitter.com/sehurlburt/status/921921604140937216
- protonfish 9y agoEven more informative could be mentioning what problem it is intended to solve.
- spyspy 9y agoThank you. No one ever describes why anything was written in the first place. And they almost never go out of their way to list the pros/cons of their system. Although I've never even used it, I loved that the BoltDB project mentions other key/value DBs and why you'd pick one over the other, right there in the readme.
- j_s 9y agoAny mention of alternatives is anathema to open source READMEs. This is why the "awesome list of " directories wind up being so useful. Edit: Useful as in "knowing is half the battle". Being able to make an informed choice is worth something, even if it takes extra effort to filter back down.
- gedrap 9y agoMaybe I'm just unlucky but the vast majority of all 'awesome lists' that I've seen are just massive dumps of links, of extremely varying quality (I mean the links themselves), which isn't that helpful.
- deleted 9y ago[deleted]
- lstyls 9y agoYou're not unlucky, but there are some gems out there. For someone like you who is experienced in the area and can tell garbage from good stuff, it's worth digging around to find the gems. This doesn't help someone who is completely new to the list topic though. Even worse they're probably going to get bad information.
- 9y ago
- lakechfoma 9y agoso...what _is_ leonardo...
- majewsky 9y agoIf you refer to SAP Leonardo, I have no fucking clue.
- s73ver_ 9y agoHell, most of the OS projects that get posted here have that very same problem. When I go to a project's site, I should be able to tell what they do and what they're for within 5-10 seconds, preferably without any scrolling (depending on screen size) and definitely without having to click on anything.
- amelius 9y agoYes, and in light of this, I still think it's pretty strange that in a project page in GitHub I have to scroll down first before I can read a description. (People usually don't link to the README file)