4 ms·
As others have mentioned, anything obscure like this should literally come with a Wikipedia (or other such) link to explain what it is, what it does. This is th
by fao_ 5y ago
As others have mentioned, anything obscure like this should literally come with a Wikipedia (or other such) link to explain what it is, what it does. This is the primary problem with small project READMEs, imo. They assume you're already familiar with them and know what the hell they are. Like, take Ironhide:
https://github.com/MrMEEE/ironhide
Optimus Support for Linux Through VirtualGL - PPA version also available
That's... great. So it's doing something with GL, and it's running on Linux, but uhhh.
my branch of the original bumblebee project..
What is Optimus? What is Bumblebee? The trick of it is that it links to a blog where neither of these terms are ever explained. Maybe it's to just look impressive on someone's CV? How could I even tell the difference?
Likewise for this project, all you need in the README is one line that's like:
X-Transformers is a re-implementation of Machine Learning Transformers that has been built based on experimental Arxiv papers
It's a one-line fix but it'll stop people like me being confused as to whether or not you're implementing a new HTTP header
- nerdponx 5y agoI would agree if this were some kind of public release announcement. Would you say the same about an experimental programming language based on a bunch of recent PLT/CS research? That's pretty much what this is, but for machine learning. It's not meant to be "for the public", it's effectively research.
- enchiridion 5y agoWe're talking 2-3 sentences to explain what's going on. A researcher releasing work publicly on github is presumably doing so too spread the ideas.
- skybrian 5y agoSure, they have some audience in mind, but not necessarily us. There are a lot of documents that are public but are meant for a specialized audience. If they were meant for the general public, they'd be written very differently. Sharing a link on Hacker News is effectively taking it out of context and sometimes it's up to us to add that context back in. The author doesn't owe it to us.
- fao_ 5y ago> The author doesn't owe it to us. There are like 6 different definitions of what a "transformer" is and none of them fall under "machine learning". If you have a README, then that implies its intended for others to read, and so it should be made with that in mind. If I happened to be interested in machine learning, this would be a project that I would bookmark for further use -- except I wouldn't know to bookmark it because they didn't bother to include a total of two words ("machine learning") that give context of how to parse the word "transformer". The fact that the owner didn't provide that context is not excused by the fact that the repository owner decided to implement a handful of research papers. It absolutely is the responsibility of the authors of projects, and the authors of README files, to provide context about what something does. The entire point of the README is to clear up ambiguity about what something is. You might as well say, why not include a README? People who are using the project know well enough how to run it!
- nerdponx 5y agoThis is BS. How many obscure security, devops, etc tools get posted here without so much complaint? Paid products, public releases, etc. are different and are treated differently.
- fao_ 5y ago> This is BS. How many obscure security, devops, etc tools get posted here without so much complaint? From me? Or are you lumping me in with all the "nay-sayers", despite the fact that I'm trying to offer criticism of a problem that's pretty common in computer science and outside it?
- skybrian 5y agoNormally people will find a Github repo in a way that gives them more context about what it’s about. For example, someone might link to this repo in an article about machine learning. There is always context and sometimes you don’t have it. Do you expect everything to be written in English for your benefit? But sure, it would be nice to clarify things for random passers-by so they know it’s not the droid they’re looking for. It’s just not required to do this in every Github repo.
- solidasparagus 5y agoThis repo isn't confusing for people in the field who would care about the project. Transformers are ubiquitous and need no explanation.
- deleted 5y ago[deleted]
- ShamelessC 5y ago> X-Transformers is a re-implementation of Machine Learning Transformers that has been built based on experimental Arxiv papers. Make a PR with this in the README.md. You still should - in the worst case it's rejected, but it starts a dialogue with the maintainer that can be referenced later unlike this comment which will be likely be buried and tough for others to find in the future.
- dhruvdh 5y agoIt took me 30 seconds of scrolling and skimming through the README to understand what it does, and X-Transformers is a re-implementation of Machine Learning Transformers that has been built based on experimental Arxiv papers doesn't really give any more information than what is already in the README - A concise but fully-featured transformer, complete with a set of promising experimental features from various papers. What useful extra information did your sentence add vs this?
- magicalhippo 5y agoWell it says it's about machine learning, so gives a bit more context. To me transformers is something that is used in electrical circuits...
- ncmncm 5y agoThis. The first line needs to give at least a hint which of about a hundred different meanings of "transformer" is meant. I had never heard of this use. That line would have told me that nothing I knew anything about would be useful to understand what the topic was.