> On 29 October 2018 at 12:04, Brujo Benavides <[hidden email]> 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.
On Oct 29, 2018, at 4:36 PM, Dmytro Lytovchenko <[hidden email]> wrote:
> Think about your future new user. Some empathy (i have empatic character, and i know this first hand you see).
> • What are your new user's first steps when he opened your library's web page?
> • Will he see a description? (many libraries have really bad descriptions) Some welcoming examples and a quick start?
> • What will he take as his first hello_your_library? And maybe some advanced examples too?
> • Where will he come to read the docs?
> • (bonus points) A community discussion board or something like that? Issues page on Github that is well maintained is a good first step.
- Follow your build instructions and verify that they actually work!
I hit this one just today, 2 errors in the build instructions that could have stumped a newbie. (Not an Erlang project, FYI.)
On 29 October 2018 at 22:27, <[hidden email]> wrote:
> Among other things, how should versions be handled in module headers given
> that we have an application version and perhaps a mix of module versions?
They shouldn't. There's no need for module versions to vary
independently of the application version. And there's no need to have
them (I assume you mean as comments) in module headers. That's what
source control's for.
Just generate the application version from the same
source-control-derived value. For modules, you can just use Erlang's
default MD5 scheme for module versions. Or you can make it the same as
the application version.