A little background: I started writing an essay the other day about end-to-end functional encapsulation in the pylons and pyramid contexts. It quickly got quite long and didn't seem appropriate for the mailing list. Still, I thought it could be a nice contribution to the community if I could get it reviewed and made visible. That made me think that the project was sorely lacking a formalism by which anybody can contribute structured, forward-thinking documentation. In retrospect, I probably shouldn't have brought PEP into my pitch. It seemed like the most accessible example of my target format but I guess all the process stuff lumped in with it raised red flags in folks' minds. Apologies.
Anyway, it kinda seems like people like this concept provided that it doesn't impede the important task of development. I would hope that we could actually *add* value to the project, but I guess that will largely depend on how things get implemented. I got to thinking that github might be an easy way to accomplish what we want without too much overhead. We could have a repository of essays (maybe all in wikitext format, say) that folks can clone, add to, and submit pull requests to. Pull requests will be accepted only when the essays seem like they are up to snuff, and the issue tracker could be used for moderating. Thoughts? Cheers! ~br On Nov 27, 3:50 pm, Mike Orr <[email protected]> wrote: > On Sat, Nov 27, 2010 at 9:28 AM, BrianTheLion <[email protected]> wrote: > > Still, PEPs provide something invaluable. They're a record of the > > dialectic, one that tracks the developers' mental models as they move > > toward a shared understanding. At the moment this record is either > > missing, incomplete, or spread across several individual blogs. My > > request, moreover, is that the dialectic be pulled into one place and > > formalized. > > Every documentation starts with a list of needs, then those pieces can > be filled in. If you can poke around and make a list of the main > design decisions and where they're discussed, that in itself would be > valuable, and then somebody could summarize them from there. The > Pyramid FAQ and related FAQs also seem to cover this area directly, so > it would be worth discussing how successful they are compared to a PEP > format. Maybe the FAQs can simply be expanded (and perhaps existing > answers made more concise for easier reading as the FAQs get large?). > Another important thing we need to see is your opinion of which design > features are not getting adequate coverage. Developers try to think > like newbies when they write docs, but their knowledge makes them > blind to some aspects (things that are obvious to them but not to > others), so it helps to have a perspective from somebody farther > removed from the process. > > > Note that I'm not asking for additional design > > documentation in the traditional sense. Design docs are static; they > > say "This is where we're at now" and don't include much of "This is > > how we got here." What's important to newcomers, most especially those > > that have the desire to contribute to the project at a high level, is > > not a pedagogical treatment of the existing design but an ability to > > track the decision-making process that led to it. > > Ah, that may not be in the FAQs as much. The FAQs cover why a design > was chosen, but not what happened before that. Again, if you can make > a list of questions, especially how Pyramid is different from other > frameworks, that would prod somebody to write an answer of how it came > to be that way. Often I do that, I start writing a history on > something, and that raises questions that aren't in the list archive > so I ask the developers, and it only takes them a second to answer it, > and I incoroprate that info into the docs. > > > Another nice thing about the PEP format is that it says to the user > > community, "If you've done due diligence, we're listening." While > > public mailing lists are reasonably informative, there's typically no > > barrier to entry. Whether we like it or not this establishes a > > particular tone and context for interactions. Though the dialog on > > pylons-discuss is tolerant - which is good - it is often not as > > technical or productive as it could be. The basic expectations of a > > PEP, on the other hand, are that the authors have reviewed the > > relevant documentation, spent lots of time with the code, and are > > presenting (with citations) a detailed account of their perspective > > for peer review. > > That is exactly the problem with a PEP format; it takes so much time > to write and cite. It's necessary for Python because Python has > several orders of magnitude larger userbase, and it has a tradition of > arguing the same things over and over for years, as somebody requests > a feature from another language, Guido says no, they argue for it > until it dies down, and then next year somebody else comes along and > starts arguing for it all over again. That was one of the main reasons > for the PEPs, to record the debate so that when it comes up again, > people can point to the PEP for why it's rejected. Pylons has not had > even 1% of that controversy in the past three years, so that reason > for PEPs does not exist. > > I could write some things about the history of template front-ends and > SQL front-ends and Javascript and Routes and other things in Pylons, > but these issues are so settled now and people rarely ask for the old > ways to be revived, so I'm not sure it's worth the effort. > > However, it would be worth recording how Pyramid came to its current > form, from the Pipefitters' Union to Ben looking for a component > architecture/event system for Pylons 0.9.7, to ChrisM's wanting a > meta-framework of underlying services especially in the area of > configuration, to Ben's realization that BFG already had the pieces > that would be built and it was flexible enough to accommodate Pylons, > to the merger that created Pyramid. Hmm, after the tutorials are > finished... > > > Maybe the best way to understand my request is for me to state my bias > > outright: From my perspective, the Pylons project is engaged in > > nothing short of a full-blown research exercise. Groups of people have > > been doing this kind of thing for a long time and they've pretty much > > all arrived a common mode of discourse. See also: "RFCs," > > "Transactions," "Nature," etc., etc. PEPs are just Python's version of > > dedicated research literature and I'm the guy suggesting that we're at > > the point where we should probably start our own journal. > > A journal would be good. That's kind of like a blog dedicated to > Pyramid's evolution. The problem I have with the PEP format is that > it's a bit rigid and time-consuming to write, whereas just simply some > essays can capture most of the essential parts effectively. > > -- > Mike Orr <[email protected]> -- You received this message because you are subscribed to the Google Groups "pylons-discuss" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/pylons-discuss?hl=en.
