Closed adiakritos closed 6 years ago
wingrunr21
commented
6 years ago The first line of the README is accurately describing the gem. Griddler requires an external service to convert incoming email to an HTTP Post request. It isn't actually receiving email and adding a README entry that says it allows a Rails app to do so would be inaccurate.
adiakritos
commented
6 years ago @wingrunr21 Perhaps you can explain what it can be used for. I get what it does but that doesn't help me.
The tutorial the readme links to says this in the first sentence, "thoughtbot, released a gem that will help you receive email in your Ruby on Rails app called Griddler."
https://sendgrid.com/blog/receiving-email-in-your-rails-app-with-griddler/
Are they inaccurate? The point is that it's clear what the gem can be used for.
What is a tire iron for? "To unwrap rubber from a cast of solid material", or, "To help make removing a tire from a vehicle wheel easy".
Even better might be, "To help make removing a tire from a vehicle wheel easy by unwrap rubber from a cast of solid material".
Just saying... I took me a few reads to get what the hell the gem is for because I see we're using it in our app. Would save people time if the purpose were more clear as I've outlined above.
wingrunr21
commented
6 years ago @adiakritos I'm happy to answer questions but not super thrilled with the tone you're taking here.
This project normalizes out HTTP POST requests for various email services that provide an inbound parse service. Basically, these services allow people to send email to them (via a configurable email address), they parse that email into its disparate parts, and then POST that email to the API endpoint that you've configured.
Most of these services POST via some kind of JSON envelope. Griddler exposes the controller action and then allows an adapter system to allow that JSON envelope to be normalized (see adapter list here).
So, you use the project to "receive" email but not in the same sense has having an actual inbox. You have to have one of the external services to actually do the email receive + parse + POST.
You should make the very first line of the readme say this:
"Griddler allows your Ruby on Rails application to receive email."
The line goes straight into a HOW it does what it does and assumes the reader knows why they would want an endpoint that converts whatever into a POST request.