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 > [email protected] http://mail.pm.org/mailman/listinfo/houston Website: > http://houston.pm.org/ -- B. Estrade <[email protected]> _______________________________________________ Houston mailing list [email protected] http://mail.pm.org/mailman/listinfo/houston Website: http://houston.pm.org/
