readme: markdown hero

[missinglink]

finally! this is one of the major discussion points when we started looking at the logo design.

I always liked the graphical headers for projects like https://github.com/caddyserver/caddy which have a level of sophistication that we've previously been lacking in our github docs.

I'd like to eventually roll this out across all repos, but until we're happy with it I'll just merge it here and we can all contribute changes to it.

A few things I'd really like to get across:

• It's a mature and managed professional open-source project (the logo helps with this)
• That there is a hosted SaaS solution from the core team which helps cover the costs of development
• An overview of the project for someone landing on any random repo as their first impression
• Links to documentation, community chat etc.

[missinglink]

@orangejulius @Joxit @elioqoshi thoughts/feels?

[Joxit]

Very nice and pro !

A modular, open-source search engine for our world.

This is very catchy ! :smile:

[missinglink]

Three things I'm not 100% sure about are:

• Should the logo be bigger/smaller/as it is?
• The text below is super informative and nice for new users but maybe too verbose? I considered having the arrow closed by default but that's not great either.
• After this 'hero' block, do we have horizontal break or just put the first <h1>?

[Joxit]

• The logo is perfect
• Perhaps the first paragraph should always be present (without arrow) and the second paragraph hidden under a "Why Pelias ?" closed ?
• Just the first <h1> looks good

[orangejulius]

This looks really awesome! We definitely have needed something like this for a long time. I think the logo size and general spacing are great.

My only feedback is the word 'geocoder' should appear somewhere. Personally I think it should even be in our tagline, but that should be discussed.

[missinglink]

"Pelias is a geocoder powered completely by..." ?

[missinglink]

"A modular, open-source geocoder for our world."?

[orangejulius]

After thinking about this a bit more I don't know if "for our world" adds anything with the word geocoder. it makes sense with "search engine for our world".

Here's some of the terms we've used to describe Pelias in the past:

• modern: I think by this we mean that it's built on recent web technologies like Node.js, and not something older like C++. Not a bad thing to get across
• modular: Here we are advertising the fact that Pelias is built up from smaller components that can be used only as needed. Since the first days of the project someone has only needed to import Geonames, OSM, and OA if they need each one of them, for example. This is a pretty nice property to talk about, but I think it also implies complexity, which is a common criticism of Pelias
• distributed: I guess we took this from the fact that Elasticsearch can scale across many individual machines. It's probably not the most important thing to convey these days? Pelias also works equally well on a single small machine for a small part of the world
• geographic search engine: I really dislike this term. To me it seems like its trying to make something sound more impressively complicated. For example, some recent press articles about Mapzen/The Linux Foundation describe Pelias as a "Distributed full-text geographic search engine" and that is just the worst. Besides, the Pelias team has had many internal discussions over the years about the difference between a "search engine" and a "geocoder" and we've pretty firmly come down on deciding that we are a "geocoder".

Our current tagline in the pelias/pelias repo is "Pelias is a modular open-source geocoder using Elasticsearch." Later on in the readme we expand that to "A modular, open-source geocoder built on top of Elasticsearch for fast and accurate global search."

I still think those are probably the best we've come up with, and we should use something very similar everywhere. @missinglink what do you think?

[missinglink]

Yeah, I looked through our existing copy and articles written at Mapzen as well as copy I've written for Geocode Earth in the past.

I personally don't like the existing tagline "Pelias is a modular open-source geocoder using Elasticsearch." because although our choice of database engine is important I don't want it to define the project.

I've purposely omitted it from the description I wrote today and substituted it with more accessible and easy to digest language that doesn't mention any specific technology such as nodejs or elasticsearch.

I feel like we can go down two paths here:

• A list of ingredients
• A philosophy of development

I was aiming for the latter, admittedly at the expense of the former.

[missinglink]

When Carly and I were doing the Geocode Earth 'value statements' we split them into two different categories:

• Commercial Values
• Mission Statement

For Pelias 'commercial' doesn't really suit, but we could substitute 'Technical Values'.

What I was aiming for was to describe the project mission in the header because they are main reasons people should adopt Pelias, rather than specific Technical values?

[orangejulius]

Ah, I forgot the one about "powered by Elasticsearch" in my list. I agree that's not the most important thing.

I really like the idea of defining the project as a philosophy of development rather than a list of specific ingredients.

So modular and open-source both fit well in there. Would "Pelias is a modular and open-source geocoder" be sufficient?

Even though my current preference is against it, I do think its worth it to discuss using the term "geographic search engine". The "official" definition of geocoding is in fact rather strict (converting addresses to coordinates), and I could definitely see how defining the project as a geocoder could be limiting. Recent proposals like the explore API are definitely outside of that definition, although strictly speaking, I don't think autocomplete would even qualify.

I think its important that the word "geocoder" appears early in introductory material about Pelias, not only for SEO but because I doubt many people search for a "geographic search engine", but I could see how setting a broader definition of the project could be useful. Its the same reason why businesses set very broad goals like "to organize all the worlds information".

[missinglink]

Yes agreed about 'geocoder'.

Can you please open a PR for your version and we can discuss it there?

[missinglink]

Oh I actually really like how it renders on my phone ;)