[erlang-questions] Erlang checklists

[Loïc Hoguin]

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
> 
> *It*
> 
> 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 
is for.

For example:

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

Cheers,

-- 
Loïc Hoguin
https://ninenines.eu