[Catalyst] catalyst book

[Jonathan Rockway]

* On Thu, Jan 31 2008, Evan Carroll wrote:
> Make a wikibook (obligatory answer).

This is a fine idea, and something that I might consider the next time I
write a book.  But really, I don't *love* writing instruction manuals;
it's easy to find something else to do when you're not being paid.

Wikibooks generally suffer from bikeshed painting and a lack of
coherency.  Basically, the barrier of entry is too low, and there's no
incentive to do a good job (because someone else will just fix it,
right).  This results in a product that's only mediocre.

If you like writing Wikibooks, knock yourself out.  For me, the
effort/reward ratio is too low.

> Everyone should upload their notes when they're learning a framework
>  to wikibooks. Prior to wikibooks, I found that before I finished
> learning any piece of software I had 50 tomboy's, now I spend the
> extra effort to just add navigation.

This is also fine, but the result is usually a shell script or "follow
these steps exactly", not a document that increases your understanding
of the concepts.  Teach a man to fish... and all that.

> Check out the Moose book for an example.
> http://en.wikibooks.org/wiki/Programming_with_Moose  It isn't the best
> thing since sliced bread, or a commercial-grade book but it is free
> and anyone can improve upon it without any knowledge of a VCS, or a
> commit bit.

The thing about writing a book is that you really need to understand the
underlying concepts so you can show the reader what they mean and how
they fit together.  In the case of the Moose book, you continually
ignore parts of Moose that you don't understand (and refuse to
understand); this really diminishes the value of the book.  Like I say
above, it's not coherent, and it doesn't teach anything.  "perldoc
Moose" makes for much more enjoyable reading.

When writing a book, you should be objective.  Document all the
features, even the ones you don't use every day.  If you're not
absolutely sure about how something works, you need to keep researching
it until you do understand how it works.  Also, save your opinions and
"this sucks" for your blog, and your "suggestions for improvement" for
the Moose mailing list.  They have no place in a book.

> By any means, it is the publisher's decision if they don't want your
> sale. And justifying yanking your format of choice because of piracy
> is lame and shitty.

I think you are confusing the difference between the words "my" and
"your".  Personally, I prefer paper books.  Much easier on my eyes, and
a needed break from staring at my computer screen.

Obviously you disagree, and I'm sorry that your needs couldn't be met.
If you'd like a book in a different format, I'd be glad to write one for
you for $60,000.  Doesn't $40 for a paper copy seem more appealing now?

Regards,
Jonathan Rockway