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.
