[pm-h] The Perl Cookbook project - update

[G. Wade Johnson]

Hi Brett,

On Sat, 19 Nov 2011 11:53:20 -0600
"B. Estrade" <estrabd at gmail.com> wrote:

> On Sat, Nov 19, 2011 at 12:19:16AM -0600, G. Wade Johnson wrote:
> 
> <snip>
> 
> > The current approach is based on (a private) github repo. But,
> > this should prove up the ability for many of us to work on recipes
> > collaboratively. We are also playing with a wiki approach to
> > simplify keeping the files in a format that is easy for O'Reilly to
> > publish.
> 
> Before I say this, I know that O'Reilly has been in this game a long
> time, and I am sure they have a proven method far better than what I
> am about to suggest. That said, here we go.
> 
> Having been involved with technical specification documentation in the
> past that has included a ton of code examples (as many of you have)
> - some of which were purposefully broken/incorrect/naive, I can tell
> you that the #1 lesson I have learned is that you need to have a
> single set of code sources that can be maintained and
> tested/validated as easily possible. Otherwise, you're pretty much up
> a creek when it comes to ensuring correctness in the final product.

I've worked on similar projects and understand your concerns. I was
trying to avoid too much detail, given the quantity of information that
I had already written, but...

The current sources for the Perl Cookbook are available internally in a
format that O'Reilly could make available on github, if we decide to go
that route.

O'Reilly has already done another project (the Android Cookbook) in
more of a wiki style (http://androidcookbook.com/home.seam). Since the
original Perl Cookbook was not done in this style, conversion could add
to the work that is needed.

So, at the current stage, we are experimenting a bit while the authors
and publishers are working out the details of how they are willing to
allow this to be done.

> We can create tools that target the code examples/snippets to whatever
> presentation layer we want - be it a wiki or the publishing source.
> 
> Regarding the wiki, I think they are fine for collaboration (or are
> they better for "write once"? :); but I would find a cookbook
> maintained in such a way that code examples are locked-in to be the
> wrong approach. It is far easier to transform code into formats
> suitable for a presentation layer than it is to have to extract code
> from some kind of mark up.

I've worked both ways. One of the downsides of keeping the code
separate and including it in the docs is the tendency of the code and
documentation to drift relative to each other. As in almost every
programming endeavor there seems to be no "one, true way" only
trade-offs.

> Ultimately, my point is this - I think if there is just a private
> Github repo for this purpose, then that is all we need to get started.
> 
> If we focused on creating a code base that is logical and consistent
> in it's structure (and therefore easy to test/validate), then when
> the time comes it'll be easy enough to write scripts to transform the
> code into forms suitable for publishing sources.
> 
> As a side note, I think that creating recipes using brian d foy's
> "modulino" approach would work very well for us.

A lot of the recipes in the cookbook covered really small tasks
(opening a file, searching an array, uppercasing a string, etc.) In
these cases a modulino is overkill. Comparing all of the programming
cookbooks I've read, I would say that the Perl Cookbook is one of the
most useful to more junior people for this reason.

We more seasoned Perl programmers can extract the kernel of useful code
from the framework around it. But, likewise, we can also add that extra
code as needed. More junior developers usually find the simpler
examples easier.

One of the things I am hoping for the community to be able to do with
this is make multiple cookbooks. I was thinking in terms of multiple
areas of programming with the main Perl Cookbook as the foundation.
But, now that you've mentioned it, layering cookbooks in terms of
experience may also be useful.

> Finally, Wade, thank you for pursuing this!

I'm really still not sure what I've gotten myself into.<shrug/>

G. Wade

> Brett
> 
> <snip> > > G. Wade -- There are two ways to write error-free
> > programs; only the third one works. -- Alan Perlis >
> _______________________________________________ Houston mailing list >
> Houston at pm.org http://mail.pm.org/mailman/listinfo/houston Website: >
> http://houston.pm.org/
> 
> -- B. Estrade <estrabd at gmail.com>
> _______________________________________________
> Houston mailing list
> Houston at pm.org
> http://mail.pm.org/mailman/listinfo/houston
> Website: http://houston.pm.org/


-- 
Cannot say. Saying I would know, do not know, so cannot say.
                                  -- Zathras - "The War without End"