README Review / Feedback #502
Description
Hi. I offered to give feedback on projects on lobsters. @antonmedv requested, so here you go:
First Impressions
The introductory sentence is clear about what expr-lang does. You should follow up or add an explanation of why expressions are useful for many things in programming as opposed to statements.
user.Group in ["admin", "moderator"] || user.Id == comment.UserId
I'm not a go user. To me this looks like it should be valid python or js, or very close to it maybe clearly describe how it would be difficult to do that in vanilla go.
Writing for two Audiences
I think you have two audiences for your readme
- People who want/need to learn expr-lang because it is embedded into some other project they are using. They want a normal programming language tutorial
- Expr language embedders
For new users I think your goal should be to get them playing with it quickly, and getting them familiar with the language.
Btw, your "play with it" link fails with a go build error.
https://go.dev/play/p/z7T8ytJ1T1d
Also, be aware that people coming to Expr-lang from this side might not be familiar with go yet. They are going to want a very task focused approach.
For Expr Lang embedders, you want to convey the type of configuration problems they can solve. Maybe show some toy examples.
Start with some type of sample app, say a package deployment system
Next add the simplest Expr-lang integration.
Maybe add the caveat "at this point your thinking, why don't I roll my own config"
...
Then add more specialized primitives for Expr-Lang tied to the toy app.. I assume this is possible. Go functions that are exposed in Expr-lang.
Then show something elegant.
SICP does this amazingly. Here is a number, here is a complex number. Here is a polynomial. Here is derivation. Here is derivation working on polynomials. Here is derivation working on a polynomial with complex exponents.
Add a section for embedders saying "who this is for" "who this isn't for". For the projects it won't work well for, point them somewhere useful.
Extras
Link to some videos, presentations, screencasts of the creators using the language.