alt Hacker NewsI love this. Most readmes are plain bad. I think the most egregious is when a readme doesn't state what the project does. I get that not every project is aimed at the public, but if you go through the bother of creating a readme file, why not go the extra 10 centimeters by writing the most basic information? Other issues: * outdated (and thereby wrong) information * using un-introduced abbreviations (bonus points for abbreviations that have common meanings, e.g.: EG, NB, IE, ETC)
Replies
> using un-introduced abbreviations (bonus points for abbreviations that have common meanings, e.g.: EG, NB, IE, ETC)
Every company should give their new employees a list of in-company invented words and abbreviations, so that you don't search for them online and then feel like an idiot for not being able to find them. Especially when the older employees use them as if they are common knowledge.
Could have used extra 1 centimeter to format the comment's list properly. :)
> go the extra 10 cm
Going to steal this
There are a number of (newish) AI projects on GitHub whose README make zero sense. I would read it three times but still have no idea what it does.
If your project is aimed at average developers yet someone with professional software engineering experience like me cannot understand it, sorry I'm not going to use it.