I’ve put the explanation in a github repository, hopefully the same one it will be implemented in. Looking for feedback regarding:
And also if anyone wants to join the project.
1 + 2.
I think a resource where a user can “easily” get guides on how to do “general” things in Crystal could be really handy. As you said file management but I also think you know how to work with json, and other stuff.
Personally, I am unsure but my personal idea would either be to have a github repo where guides are put under “categorize”, like a category could be “file-management” and an article to that article could be “how to read a file”. And then build some kind of html site with these guides and put them all on some sort of website. But you could also build a web server where users can create an account own guides. And then there can be some workflow, on making a guide “official”. The web server idea would be a lot more work to set up but could lead to an enchanted way for user-generated content.
I mean in my personal opinion I would like it to include everything Crystal. But I think that kind of expectation could be a bit overwhelming. My personal idea would be to start making a guide in for example file management and make it really solid and then you feel happy about it, publish it, and start on another category. I think at “launch” it doesn’t have to be complete and guides can be created after hand. And as always when it comes to guides, quality over quantity.
Well, one important thing you have to have in consideration is that for people to use such a guide, most users would like it to stay up to date. And some users may like to be able to read guides made for older versions. So I think you will have to do some thinking around versions and maintaining if you are planning this to be a long term thing.
I am currently working on learning mode for Crystal on Exercism. Which aims to be a bit like the Crystal book but with more practical practice. I am up for partnerships, if you would like to do any. And if you want help with reviewing “guides” I am up to help and if you like to help on the learning mode for Crystal so are you also welcome.
Thanks for the feedback.
But you could also build a web server where users can create an account own guides. And then there can be some workflow, on making a guide “official”. The web server idea would be a lot more work to set up but could lead to an enchanted way for user-generated content.
I definitely want to avoid this complexity. I was just thinking a static site with a public repo people can contribute to.
I am currently working on learning mode for Crystal on Exercism. Which aims to be a bit like the Crystal book but with more practical practice. I am up for partnerships, if you would like to do any. And if you want help with reviewing “guides” I am up to help and if you like to help on the learning mode for Crystal so are you also welcome.
That would be great. One of my goals is to not duplicate any work done by you or awesome-crystal etc.
The Crystal book is a good place to put this. Specifically the Guides section is meant for these kind of materials. Maybe this title doesn’t fit 100% but short recipes are definitely meant to go in there (ref Reorganize content structure · Issue #384 · crystal-lang/crystal-book · GitHub). We can reconsider the section name is something else makes more sense.
The infrastructure is already all set up: It’s a static site, built from a git repo, there’s support for interactive examples and the content is versioned per Crystal release. Integrating it into the book has some synergy effects, such as a great visibility and established maintainenance workflows.
So I see not much reason to create an external resource for this.
@straight-shoota This was one of my biggest questions, so it would be great if I could just integrate it into the crystal book. Couple of things though:
- shard recommendations for common tasks - hopefully working with awesome-crystal on this
- curated explanations of how to use the standard library
Yes, I can imagine some stuff going into the tutorial, and some into the guides.
About shards, it’d feel odd to recommend some particular shard outside of the official ones. Perhaps it can have a place in the book if it’s written in a way that do not tight to a specific shard, and points to the right place in awesome-crystal.
About the stdlib, definitively! We’re missing that for sure, and some might even be part of the api.
True. There is certainly some overlap there.
In general, the idea is for Tutorials to have more in-depth courses that serve as an introduction to broader topics, but also cover a lot of details. And Guides are smaller, isolated resources on individual topics. So I think cookbook recipes would typically belong there, but some could also be in a tutorial format. This structure isn’t fully finalized though. The important part is getting the contents. We can reorganize the structure to fit if it becomes necessary.
I understand that this aspect can be a bit dicy. The Crystal book should try to not influence the ecosystem as preferring one shard over another. Using a shard that is established as a standard solution in the community would be fine, though (IMO).
However, I think most shards should usually have their own documentation including cookbook recipes for how to use it.
Definitely. There are already examples for that.
Thanks for the feedback everyone. I chose an terrible time to start this since I’m traveling, so I’ll start this in a few weeks hopefully, in the crystal book.