[pm-h] The Perl Cookbook project - update

[B. Estrade]

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.

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.

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.

Finally, Wade, thank you for pursuing this!

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>