I think a github repo is probably the easiest way to do it and to collaborate. We all know how to write RST as we do documentation and github renders it :)
But Mike's bitbucket is also great choice On Nov 29, 11:05 am, BrianTheLion <[email protected]> wrote: > 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.
