[erlang-questions] Erlang checklists
Mon Oct 29 13:28:18 CET 2018
On 10/29/18 1:12 PM, Roger Lipscombe wrote:
> On 29 October 2018 at 12:04, Brujo Benavides <elbrujohalcon@REDACTED> wrote:
>> Hi Lloyd,
>> This is the checklist we have at Inaka: https://github.com/inaka/guidelines/blob/master/OPEN-SOURCE.md
>> It's has a clear and useful README.md
> That aside ;-), one of my personal bugbears about README files is that
> not enough of them tell me what the project *is*.
> For example:
> "Project MooCow aims to be performant, extensible and simple to use."
> Great, but is it a database, an HTTP client, a BDD tool or what?
The first sentence of the README file should not only say what the
project is, but also persuade people to use your project instead of one
of the alternatives. In other words it should clarify who your project
* MooCow is an HTTP client for Erlang.
* MooCow is an enterprise-ready HTTP client for Erlang.
This simple addition can be interpreted a number of ways, and sometimes
users will misinterpret, but it suggests that it does more things than a
plain HTTP client, for example export metrics and/or allow monitoring
tools to be plugged into it.
Don't make the sentence too long though, limit to 2 or 3 attributes that
make the biggest difference compared to other projects, or that are the
biggest strengths if there are no similar projects.
That first sentence should be used everywhere where a short description
is to be provided.
Remember, we form our opinions on most things in a split second very
early on when we are exposed to something new. The more alternatives
there are the most important influencing that split second becomes.
More information about the erlang-questions