Ok, so. Tom Hukins of Milton Keynes Perl Mongers was kind enough to write to their mailing list and say nice things about the new Catalyst book and there was one comment that really stood out.
Those of you who failed to fall asleep during the technical talks I've presented this year will notice some overlap between "what Tom thinks too few people know about" and "what this book covers".
I think if you s/Tom thinks/\@authors think/ you get a pretty decent summary of what we were trying to achieve.
One of my biggest annoyances with technical books is that they generally present a somewhat contrived "example application" and cover what code you type to get what result at each stage, plus explain what that code's doing.
This is useful. If you throw out the contrived single example thing and just show code fragments and also happen to be absolute geniuses, the result is Kernighan & Ritchie's The C Programming Language, a book I have bought twice, leant out twice, not got back twice, and keep meaning to buy a third copy of because it's wonderful.
However, that teaches you to use the language in front of you - it doesn't show you how to structure a project, how to think about a project, and how to develop a project in a sustainable, well-tested way.
In the book, we've tried to do all of that as well. To our minds, the priorities of somebody starting with Catalyst should be something like
1) Produce code that lets people do something cool
2) Produce code that does that something reliably, and in a way we know it's going to keep doing it reliably
3) Produce code we can keep adding more somethings to reasonably quickly
99) Produce code that uses Catalyst and DBIx::Class
Oh, and of course I missed something:
-1) Be done and down the pub
This means that the book covers getting a basic build environment (make, gcc, configure cpan etc.) together, options for installing without root, some basics of Moose and perl OO, the philosophy of MVC behind most Catalyst apps, and perhaps more importantly: We wrote tests as we went along, just like we would on real projects. We try and explain why we made the choices we did and what the alternatives are. We talk about application design and domain modeling, and write code that's actually not using any Catalyst or DBIx::Class modules at all and could be re-used in any environment, and we test that code too.
Perhaps best of all, sometimes we kept the mistakes we made when we were writing the code ourselves, show how the tests we wrote caught those mistakes, and how we went about understanding the bug and fixing it.
Doing all this was ... not just a challenge, but a risk. Some of it, especially the flow-of-development stuff and the highlighted diffs to show changes to code rather than simply the final states of code after those changes, our editors thought was, well, potentially more stupid than brave, and they expressed pleasant surprise when it worked out. I'm still amazed it worked out, because a lot of this was at least in part my idea and the one thing I'm sure of after this was I had no idea how to write a book and still don't except for "get really good co-authors and hide until they've written it".
However, it seems that trying to include general "things not enough people know" into the process but with a Catalyst-ish slant was a huge success, to the point where I think this is probably something we need to look at how to feed back into the documentation efforts for the projects involved.
I'm not sure where we start to do this though.
I think trying to show test examples alongside code examples in tutorial materials is worthwhile. I think we all need to write more "extending X" documentation that shows idea, design, code and test. And I keep wondering if we could package things like the "getting going with CPAN" and similar steps up into not just linkable documents, but perhaps in order to maintain the flow of progression for newbies includable templates - i.e. something where you end up with "cpan Catalyst" because you said "basic cpan setup doc for module Catalyst please" somehow.
What I am absolutely sure of is that we all need to spend more time thinking about how to explain the why and when of feature usage as well as the what and how, and to remember that our users don't just need to write code that invokes our feature, they need to write robust, hopefully fast running tests to ensure that their code achieves their desired result in doing so. And we should also remember that the more our documentation guides users down the path of finding not just a feature that solves their problem but the right feature to solve their problem with and express clearly their intent in the process, the less time we'll spend fighting expectation and culture mismatches when we could be welcoming new users and seeing how many of them we can shout "well volunteered!" at and get away with it.
Which, really, is what it's all about ...
-- mst, out.