There are a couple of changes related to documentation we would like to arrive in mid-term.
I would like to discuss the general scope of the
crystal-lang/crystal-book and the general aspect of the changes.
- It should be a reference for the language
- It should be a reference for the built-in tooling
- It should have introductions for using Crystal in a couple of scenarios and point in directions to keep digging deep
- It should some sections for different aspects (ie: concurrency, performance, database, etc)
- It should have guides for usual best practices for the ecosystem (ie: publishing shards, docs, CI)
The last item will probably evolve faster than the others but is content I would prefer to have an official reference for rather than posts in different places. Definitely those posts can be used to keep the content up to date to things changing outside crystal.
The main thing that is currently in the book that I would like to see them changed:
- Installation methods. I believe is better to put that content on the website itself. I don’t want a book that tells me the installation method for 15 distros and their caveats.
- The initial opening is the readme of the repo instead of an introduction of what the content is. (Note: the
learnlink in the website jumbo banner should point to this intro I guess)
- The table of content should be adapted for better navigation of the above goals.
And last, usually, books have some full sample code the reader can checkout and use. Not for all snippets, but for some chapters/sections it would make sense. These samples could be stored in the same repo to keep them in sync easier I guess.
What other general aspects will be good to have in mind to achieve a better learning and reference resource?