[ruby-talk:01244] Re: Any FAQ requests, updates, ...

From: Dave Thomas <[e-mail]>
Sent: Friday, February 04, 2000 7:48 PM

> I'm making a pass through the English language Ruby FAQ, tidying up
> some stuff and checking it for accuracy.

THANKS.

> While I've got it open on the operating table, does anyone have any
> requests for changes, things to include, things to exclude, or
> whatever.

I was tempted to include a long list of things, which I realized would make
the FAQ serve as a stand-in for an English "Programming Ruby" book and an
English "Ruby Cookbook" book, but which is too much to ask of a FAQ.

But there are a few fairly simple things that illustrate some sorts of
changes that I think would be useful.

In "1. General questions", a description of the intended scope and purpose
of the FAQ. Are you supposed to have read all the other documentation first?
Or should you start out reading the FAQ?

A description/glossary of otherwise undescribed terms (for example, explain
what mix-in means, although there is some mention of this is other
documentation).

In "7.9 How can I use less to display strings?", since Ruby closes files for
you, I don't understand the need for this. (In general, a little more "why
do you need this?, why do things work this way?" information scattered
throughout the FAQ would be helpful.)

In "7.15 How can I sort strings in alphabetical order?" and in some other
places, an example of the actual code would help beginners.

I would change (mildly) jargonistic/implementation terms. (For example,
change "is parsed as" to "is interpreted as" or "is equivalent to" or most
simply and directly, "means".)

Conrad