Do you want to go to an event where you're the only person not wearing a suit? Representing yourself well is important. The same goes for representing Crystal. Here are my humble thoughts on how we can present crystal to the world in a better light. With examples of what we did right (and wrong) right from the biggest crystal projects
If you look at Kemal's website you will notice that it is a fast framework. That doesn't do it justice. That is why it is Lightning-fast. They have a graph to prove it.
Don't just say something, prove it! if you think your framework has beautiful code. Tell me it is beautiful and prove it with a code sample. Amber needs to stop just saying it is "highly performant" and actually prove it.
Here is an exerpt from the official athenaframework website
Athena Framework integrates each component into a single cohesive, flexible, and modular framework. It is designed in such a way that allows for it to accommodate the majority of use cases in a way that can be as simple or as complex as required
Lets rewrite this in a soccint way
Athena Framework wraps all athena components into a single, cohesive whole. It accommodates simple and complex requirements alike.
The crystal documentation states that BigInts are "arbitrarily large". What does that mean? Can they hold an infinitely large value? Or are they so large that I will never possibly run into a situation where they are too small? If increased clarity means you need to use more words then you may use more words.
Crystal is great at this, we all understand that crystal was born because its creators wanted C performance with great syntax.
But why was Amber created? Its landing page doesn't tell me
When you want to tell people about your project. Tell them WHY you made things the way you did, get into the details. This lets people know your project on a deeper level. The more open you are the better.
Crystal did a great job when explaining the use of Time.monotonic. It did not assume we knew anything about wall clocks and regular clocks. This meant that whoever reads those docs will understand them easily. Unlike the case with "Arbitrarily large BigInts"
If you want to see an example where this law is broken go look at the documentation for any machine learning library.
Do not tell me what a thing is, tell me why I should care. If your framework is highly reusable. Tell me why I'd care about that feature and how it could help me.
Nobody cares about your project. They just care about how it can help them.
These are just a set of guideposts here to help you on your journey. With collaboration from the community, we will be able to polish this document and put it on the crystal website!