Note: This reply is sent directly to you, not to the list.
Excellent. Hopefully, I'm not overstepping myself by sending critiques,
but I have some suggestions:
1. The third paragraph kinda comes across as apologetic and hedging too
much. I thought about possible ways to rephrase it, but ultimately, I
think it would best be simply deleted. It doesn't seem to actually
serve any useful purpose within the text of the tutorial.
2. The "What do they resemble in other languages?" should probably have
something in it, or be removed entirely without any reference to
resembling something in another language. You might consider making a
note about it being a work in progress, with a solicitation for comments
from readers who understand symbols about what they resemble from other
languages. If you do so, I'd recommend a very strong disclaimer to the
effect that resemblance is not the same as equivalency, and one should
take care in thinking of symbols as being similar to features in other
languages. In particular, you might mention:
a. Ruby symbols bear a superficial resemblance to barewords in
Perl, but are not much the same in practice.
b. Ruby symbols bear some resemblance to globs, though globs are
limited to use in relation to filehandles. By extension (and,
unsurprisingly) Ruby symbols also bear some resemblance to the
treatment of globs by the Perl module, Symbol, though it is only an
unreasonable facsimile of Ruby symbols because it is just a wrapper
for globs meant to make them more symbol-like in appearance.
c. Ruby symbols are similar to Lisp symbols, with the exception
that in addition to the characteristics of symbols in Lisp, they are
also objects in Ruby.
3. In "What are symbols?" you might consider drawing a direct
comparison between symbols and numbers (or even integers), in particular
as regards their relationship to strings. What I mean by this is that
you might say:
:symbol is to "symbol" as 1 is to "1"
4. Another possible section to include in your tutorial might actually
be a transition between the "What do they resemble in other languages?"
and "What are symbols?" sections: "What else do they resemble in Ruby?"
This occurs to me mostly as a (perhaps better) place to put my
comparison of symbols to numbers:
:symbol is to "symbol" as 1 is to "1"
5. In the "What are symbols?" section, when you bring up the results of
:steve.to_i, you might consider mentioning that the integer to which a
symbol is translated will be different in one program than in another,
and that the reason for this is that Ruby is simply using this integer
to keep track of the symbol internally, so it's not a "random" number.
As a point of academic interest, this is because there's a hash table in
which Ruby keeps track of these things, essentially using integers as
keys by which it keeps track of symbols, though I'm not sure that's
something useful to an explanation of symbols at the level of this
tutorial. In short, I think it's a good idea to mention something about
why :symbol.to_i produces an immutably set integer so that new Rubyists
won't start making assumptions about where the number arises and try to
use it improperly as a result.
6. When you talk about capitalizing a string derived from a symbol, you
might also mention that you could, rather than using
:steve.to_s.capitalize, just use :Steve. This is more in keeping with
the point of a symbol, I think, if your capitalized version isn't meant
to have a direct connection in the program logic to :steve itself. If
it were me writing it, I might end up using an example that looks like
this, to demonstrate that from a program output perspective, both
approaches render the same result:
#!/usr/bin/env ruby
mystring = :steve.to_s.capitalize
puts mystring
puts :Steve
7. I think you forgot a colon in "A symbol is not (Just) a Name".
Either that, or I didn't understand what you were trying to demonstrate.
You also seem to have forgotten a closing parenthesis in the same
section. I might also suggest replacing the words "to hold" with "as",
when discussing the practical relationship between a symbol and a name,
since a symbol technically doesn't "hold" anything -- though I only
recommend the substitution, really, to forestall potential criticism.
8. In "What can symbols do for you?" you might consider, in addition to
mentioning that you can create a string from one using .to_s, revisiting
the fact that a symbol is essentially treated as a string when used in a
string context (such as puts :symbol).
9. In "What are the advantages and disadvantages of symbols?" you say
"The granddaddy of all advantages is also the granddaddy of
advantages:". I don't get it, unless that was a typo.
10. You might also mention another advantage of symbols, which pertains
more to metaprogramming than to the sort of programming with which most
programmers are familiar: symbols don't exist until you refer to them,
but when you do so, they spring into existence as though they had always
been there. This allows for programming logic that acts almost like
time-travel, in that you can do something with a thing that acts like
it has always existed without having to create it before you use it, and
that thing can be any arbitrary thing at all, rather than having to be
part of some intrinsic language construct. This is exactly the sort of
dynamism that makes Lisp (and, now, Ruby) so powerful.
11. I'm sure you've noticed by now, but you might consider editing the
first sentence of the "Summary" to say that symbols prompted a thread of
"more than 100 posts" rather than saying it was a "97 post thread".
Hopefully you won't take any of this amiss. Overall, I'm impressed with
the tutorial, and only recommend alterations because I'm pretty sure you
can handle it, and I would like to see your tutorial be the best it can
be. Use or ignore the foregoing advice at your leisure, of course.
name)