Introduction
I want to present here my ideas on specific actions Crystal can take to greatly improve its documentation, thus making it significantly more attractive for people considering it, and more useable/practical for people coding with it.
Impetus comes from my comments made in this thread that I want to expand upon in a structured manner, to emphasis that documentation should be just as much a priority for the devs as code development is.
Good Documentation Matters
It has been stated over and over and over documentation is vital, and will even make or break a project, but it will still be overlooked, or even thought of with disdain, by developers. But not by users.
There’s even a whole field of how-tos to help, like this and this, ignored by real projects.
One project (made aware of via Rosetta Code) which I feels gets it right is Sidef which has very functional documentation, which I suspect has fewer (people) resources than Crystal.
Documentation Can’t Be An Afterthought
No matter the technical proficiency of a project’s developers, if potential users don’t (quickly and easily) understand how to use it, it won’t get used. Rust continually faces this problem, no matter how well it’s rated technically.
TODO:
Use The Force
Luke, e.g this. There are many resources to help, pick at least one and use it.
If It’s Not Accurate It’s Not Documentation
From a user’s perspective, the worst case scenario is inaccurate or outdated information that results in unworkable code, which in many cases can’t easily be debugged. If a user is forced to consult third party sources (Stackoverflow, etc) to figure out why code doesn’t work, or how to do something to get working, then the docs have failed.
TODO:
Whenever changes/updates are made document them before
they’re publically announced. Inaccurate and outdated information should never be presented to the public. Assign each dev some section(s) of docs to maintain and update as a required responsibility .
Blogging
The Blog should be used as a primary means to educate current (and potential) users on specific coding issues and project changes.
TODO:
Make frequent (short) posts, on specific issues/topics beneficial to users. Use issues raised in forums, etc, as their sources. Create index/tag system to easily identify/access them.
Create Specific Ruby Compatibility Section
If you tout Rubyness
show how compatible Crystal is with it. Acknowledge since Ruby is the senior language the natural source of many/most Crystal users will/should come from Ruby.
To this end, (and I know there’ll be resistance to this) make Crystal as similar to Ruby as possible while still pre 1.0. Do differences e.g. includes?
|include?
, etc, really need to exist? Make the compiler accept both. You’ll create so much goodwill by doing this.
TODO:
Create prominent homepage link: Ruby Compatibility
. Show list of updated coding idioms (in both directions) to make it as easy as possible for Rubyist to do Crystal, and vice versa.
Continuing The Discussion
Crystal still has a chance, before going 1.0, to create a much better face to users, to showoff its features and capabilities. If I could decree it, I would advise dedicating a whole month to revamping, updating, and testing a system to automatically generate documentation, as you have for code development.
This isn’t an issue of resources, it’s an issue of priorities. Sidef
made it a priority to create good documentation so that potential users (certainly me) would feel comfortable (even inspired) to try it, as it has so many coded examples to start from.
Crystal is a very worthy project, and a very good language, and I want to see it being used much more. I know making the documentation more accurate, visual, and complete, will increase its usage, and thus you’ll receive more external resources and help to continue its development.
If you present Crystal right they will come (and stay)!