need your help to overhaul docs

[Chris McDonough]

While Pyramid will never be as high-level as something like Plone or
Django or Rails, it's still often more appropriate to use than those
systems in a variety of situations, not all of which require complete
Python mastery. We can do a much better job on docs for intermediate
Python developers.

If I had three months of uninterrupted time to do Pyramid maintenance
work, I'd probably work on revising the current set of Pyramid docs to
make them more understandable for intermediate developers. I might:

- Trim down the current set of docs to a more manageable length.
Currently they weigh in at over 700 printed pages. Ideally
they'd weigh in at about 500 or so. Those 500 pages would
concentrate on very core concepts; more esoteric material would
be relegated to other places (maybe the Cookbook or one or more
other sets of supplemental documentation).

- Wordsmith core concepts documentation to be less didactic and
easier to read. For instance, try to make the documentation
flow better so that the end of one chapter transitioned less
awkwardly into the next, remove 50-cent words for benefit of
non-English-as-first-language speakers, try harder to isolate
very concepts and explain them more naturally to folks without
as much Python experience.

- Intersperse tutorials between narrative chapters to introduce
a concept and/or add more examples with explanations within
narrative documentation.

Of course, I don't and will never have three months of uninterrupted
time. Even if I did, I've found that my personal documentation style is
not ideal for communication to users who have moderate Python experience
as opposed to more experienced Python developers, who seem to have less
issues reading docs I've produced.

For these reasons, I'd love to be able to engage someone-whom-is-not-me
to try to make progress on the above outlined goals.

I floated this idea to Graham Higgins (gjhiggins on IRC), a truly
excellent writer and editor, that he might try to make some progress
towards the above goals. The idea would be that Graham would
concentrate on some of the wordsmithing and trimming tasks and do a
passable job at editing the entirety of the current narrative
documentation for style and clarity. He didn't immediately laugh and
close his IRC chat window, so I took that as a good sign.

We can't expect anyone to do this without being paid for their time,
because it's a lot of work, and not very fun work at that. So I'm
hoping to raise about US $5000 for Graham to be able to do this work.

So this is me asking you for money. If I can find four other sponsors
willing to contribute US $1000, I will contribute another $1000, making
a total of $5000.

Can you convince your company to donate US $1K to this effort? The
money would be collected by Agendaless and transfered to Graham as soon
as we reached our goal.

Potential benefits:

- A larger pool of potential users (if you're a Pyramid consultant, the
benefits here are fairly obvious).

- Potentially fewer support questions and happier customers.

- Better docs for your personal consumption.

- C

[Mike Orr]

By the way, I'm planning some organization work on the Cookbook after
I finish the Pyramid/Pylons guide. I want to organize the main page
into topic chapters (database, forms, templates, deployment, etc), put
large items into subpages under their topic, and write stub pages for
the topics that don't have much material yet. So as Graham finds
material to move to the Cookbook, we can coordinate where in the
hierarchy it should go.

--
Mike Orr <slugg...@gmail.com>

[Chris McDonough]

That'd be good; it's a bit of a chexmix right now.

- C

>
> --
> Mike Orr <slugg...@gmail.com>
>

[Steve Piercy]

I'd like to donate labor to the effort by proofreading and
providing a Pyramid/Python newbie perspective.

--steve

On 2/3/12 at 10:53 PM, chr...@plope.com (Chris McDonough) pronounced:

--steve

[Ginés Martínez]

I will contribute with 50 €. Tell us how send the money.
Gins.

[Chris McDonough]

On Sat, 2012-02-04 at 12:08 +0100, Ginés Martínez wrote:
> I will contribute with 50 €. Tell us how send the money.

Thank you! I'll mark you down for that amount and if we reach the goal
we'll arrange for payment (it will probably be via Paypal).

- C

[Jonathan Vanasco]

kickstarter?

[John Anderson]

I'm busy until PyCon is over but I will donate 40hrs of my time helping rewrite docs, blog posts, screencasts, or whatever is needed the week after PyCon

On Feb 4, 2012 12:14 PM, "Jonathan Vanasco" <jona...@findmeon.com> wrote:

kickstarter?

--
You received this message because you are subscribed to the Google Groups "pylons-discuss" group.
To post to this group, send email to pylons-...@googlegroups.com.
To unsubscribe from this group, send email to pylons-discus...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pylons-discuss?hl=en.

[Simon Yarde]

I would be happy to personally contribute $50 to the effort. Please add me to the list.

Perhaps this is an amount other independents could put forward, and together another 18 of us might represent one of the $1000 company contributions?

Best, S

[Chris McDonough]

On Sun, 2012-02-05 at 10:11 +0000, Simon Yarde wrote:
> I would be happy to personally contribute $50 to the effort. Please add me to the list.
>
> Perhaps this is an amount other independents could put forward, and together another 18 of us might represent one of the $1000 company contributions?

Great, thank you, will do...

- C

[Wyatt Baldwin]

I'll commit to $100.

[Chris McDonough]

On Sun, 2012-02-05 at 11:37 -0800, Wyatt Baldwin wrote:
> I'll commit to $100.

Much appreciated!

>
>
> --
> You received this message because you are subscribed to the Google
> Groups "pylons-discuss" group.

> To view this discussion on the web visit
> https://groups.google.com/d/msg/pylons-discuss/-/Ct3kw0v6GfIJ.

> To post to this group, send email to pylons-...@googlegroups.com.

> To unsubscribe from this group, send email to pylons-discuss
> +unsub...@googlegroups.com.

[clemensherschel]

I will contribute $100. Thanks.
On 2/4/2012 6:08 AM, Gin�s Mart�nez wrote:
> I will contribute with 50 �. Tell us how send the money.
> Gins.

> --
> You received this message because you are subscribed to the Google
> Groups "pylons-discuss" group.

> To post to this group, send email to pylons-...@googlegroups.com.
> To unsubscribe from this group, send email to

> pylons-discus...@googlegroups.com.

[Chris McDonough]

On Sun, 2012-02-05 at 15:02 -0500, clemensherschel wrote:
> I will contribute $100. Thanks.

Many thanks, I'll mark it down.

> On 2/4/2012 6:08 AM, Ginés Martínez wrote:
> > I will contribute with 50 €. Tell us how send the money.

[Cem Ikta]

I will contribute with 100 €. We need good docs for everyone.

Best regards.

Cem.

[Chris McDonough]

On Sun, 2012-02-05 at 16:23 -0800, Cem Ikta wrote:
> I will contribute with 100 €. We need good docs for everyone.

Great!

>
> Best regards.
>
> Cem.

>
>
> --
> You received this message because you are subscribed to the Google
> Groups "pylons-discuss" group.

> To view this discussion on the web visit

> https://groups.google.com/d/msg/pylons-discuss/-/JpF5Qlibe38J.

> To post to this group, send email to pylons-...@googlegroups.com.

> To unsubscribe from this group, send email to pylons-discuss
> +unsub...@googlegroups.com.

[Matt Feifarek]

On Fri, Feb 3, 2012 at 9:53 PM, Chris McDonough <chr...@plope.com> wrote:

Can you convince your company to donate US $1K to this effort?  The
money would be collected by Agendaless and transfered to Graham as soon
as we reached our goal.

I'm an indie, so no, but I can personally pledge $100, if that's not too small-potatoes to matter.

[Chris McDonough]

That's great, thanks.

>
>
>
>
> --
> You received this message because you are subscribed to the Google
> Groups "pylons-discuss" group.

[Iain Duncan]

We're indy too but could kick in $50.

That said, please do not just trim the expert oriented stuff and have it nowhere, that will seriously lower the quality of the docs for complex applications and people weighing up pyramid for those kinds of purposes. You'll just be hiding lots of the best reasons to use Pyramid. For god's sake, fork the pages in to two versions or something. I totally get the need, but simply trimming the docs is going to negatively affect them for many of your users, and those users are influencers (ie they encourage others to try pyramid, help others with pyramid, etc ).

My personal preference would be to have a parallel structure where each one has a link to the 'advanced details' version of the page. 

iain

To unsubscribe from this group, send email to pylons-discus...@googlegroups.com.

[Graham Higgins]

On Monday, 6 February 2012 17:54:36 UTC, Iain Duncan wrote:

but simply trimming the docs

I'll observe that's a straw man that you've brought to the party; no-one has mentioned any trimming of the docs, simplistically or otherwise.

My personal preference would be to have a parallel structure where each one has a link to the 'advanced details' version of the page. 

 

Thanks for the suggestion, indeed I have been considering the merits of such an approach.

Cheers,

Graham.

[Graham Higgins]

Iain, apologies, my response was overly stiff and formal, it wasn't meant to be - you got some unintended crosstalk from a parallel conv that I was in, soz. 

Really, "Heartfelt thanks for the contribution" was what I should have written.

I'll try and explain my thinking later, we need a Plan B as well.

Cheers,

Graham.

[Mike Orr]

+1 for splitting the manual into simple and advanced, however that's
defined. Simple = normal application usage based on the built-in
scaffolds. This would include both Chameleon and Mako, and maybe
traversal. Advanced = optional customizations such as new renderers or
ZCA.

The hardest things to split are the lists of config methods arguments,
such as the add_route and add_view arguments. You either put them all
in one place or half in simple and half in advanced. Neither approach
is ideal, but there doesn't seem to be any other choice.

--
Mike Orr <slugg...@gmail.com>

[Tjelvar]

I'm just a casual user, but I could contribute £30 (~$47), if this is
not too little.

On a related note I'd quite like to see a more mainstream book on
Pyramid. So for my own edification I'm in the process of trying to
write one. Does anyone else feel that there is a need for such a book
or is it just me?

Cheers,

Tjelvar

[Chris McDonough]

On Mon, 2012-02-06 at 22:11 -0800, Tjelvar wrote:
> I'm just a casual user, but I could contribute £30 (~$47), if this is
> not too little.

Thanks, it's great.

>
> On a related note I'd quite like to see a more mainstream book on
> Pyramid. So for my own edification I'm in the process of trying to
> write one. Does anyone else feel that there is a need for such a book
> or is it just me?

I think a book would be great, especially one that didn't need to be so
comprehensive as the original docs.

- C

>
> Cheers,
>
> Tjelvar
>

[Robert Forkel]

i'd be happy to chip in
€ 50 = 65.47500 U.S. dollars
best regards
robert

[Danny Navarro]

I'll contribute with € 50, too.

--
Danny Navarro | http://blog.dannynavarro.net

[Chris McDonough]

On Tue, 2012-02-07 at 10:31 +0100, Danny Navarro wrote:
> I'll contribute with € 50, too.
>
> --
> Danny Navarro | http://blog.dannynavarro.net
>
>
> On Tue, Feb 7, 2012 at 8:07 AM, Robert Forkel <xrot...@googlemail.com> wrote:
> > i'd be happy to chip in
> > € 50 = 65.47500 U.S. dollars
> > best regards
> > robert

Thanks Robert, Danny, and Iain. That brings us to about $1002.00 so
far.

- C

[Mark Gemmill]

Personally, the only real shortcoming I've found with Pyramid (documentation or otherwise) is that it doesn't have a "Buy that man a beer!" button. :-) So, count me in for $50 to help out. 

Mark

[Iain Duncan]

I'll observe that's a straw man that you've brought to the party; no-one has mentioned any trimming of the docs, simplistically or otherwise.

??? From the originating post by Chris

- Trim down the current set of docs to a more manageable length.
 Currently they weigh in at over 700 printed pages.  Ideally
 they'd weigh in at about 500 or so.  Those 500 pages would
 concentrate on very core concepts; more esoteric material would
 be relegated to other places (maybe the Cookbook or one or more
 other sets of supplemental documentation).

That seems like a pretty clear mention of trimming the docs to get rid of the 'esoteric' material to me. The esoteric material absolutely needs to stay, IMHO. A lot of it what makes Pyramid great to advanced developers. It should just be tucked away better somehow.

iain

[Iain Duncan]

On Mon, Feb 6, 2012 at 12:02 PM, Mike Orr <slugg...@gmail.com> wrote:

+1 for splitting the manual into simple and advanced, however that's
defined. Simple = normal application usage based on the built-in
scaffolds.  This would include both Chameleon and Mako, and maybe
traversal. Advanced = optional customizations such as new renderers or
ZCA.

On the topic of parallel docs, here's what I would do, adopt or reject as you see fit:

- The easy book/docs focusses on Pyramid in 'Pylons/Django' style, which is how most people are going to want to be introduced. It doesn't dwell on interfaces, adapters, zcml, views as classes, overriding resources through zcml, etc. Readers of the easy book just get up and running with Pyramid as fast as possible. The acid test of this stream is "how good and quick was your hit the ground running experience?" This book impresses all those people who like to write "web framework shootouts" after only using the framework for a day ( barf! )

- The advanced book goes Under The Hood. It explains what's happening and how it all is lashed together as a component architecture system, and all the myraid places you can hook into or override this system. It covers views as adapters, registering them by interfaces, zcml_pyramid, using the resource system, more on custom factories, writing your traverser, etc. The acid test on this stream is "could you replace any component in the pyramid system with a version of your own after reading all this"

I would personally make them connected. So each page in the easy book has a link to "under the hood", where we find out how pyramid actually accomplishes this and where you could tinker with how it's done.  And the advanced section heavily points at good further reading. ie, it doesn't have to be the definitive guide to using the ZCA, there already is a good one, so it being advanced, it can be fairly terse on what you use a zca interface for and point somewhere else for more details.

my two cents canadian

iain

- the advanced book digs under the hood, 

[Chris McDonough]

Pyramid's use of a ZCA registry is still an internal implementation
detail, and as such isn't really intentionally exposed to the outside
world. It won't make much sense for the docs to explain how Pyramid
works in terms of ZCA vocabulary such as "adaptation", or even link
heavily to things that explain what adaptation, etc is. Instead,
explanations of framework hooks and such should just tell them which
Configurator methods to call, just as the docs do now. Theoretically,
Pyramid may disuse the ZCA in a future major release (although it's
highly unlikely).

ZCML is purely an add-on package via pyramid_zcml, with its own docs.
The core Pyramid docs will not cover it, although they might mention it
in passing.

- C

[Mike Orr]

On Wed, Feb 8, 2012 at 9:56 AM, Chris McDonough <chr...@plope.com> wrote:
> Pyramid's use of a ZCA registry is still an internal implementation
> detail, and as such isn't really intentionally exposed to the outside
> world.  It won't make much sense for the docs to explain how Pyramid
> works in terms of ZCA vocabulary such as "adaptation", or even link
> heavily to things that explain what adaptation, etc is.  Instead,
> explanations of framework hooks and such should just tell them which
> Configurator methods to call, just as the docs do now.  Theoretically,
> Pyramid may disuse the ZCA in a future major release (although it's
> highly unlikely).
>
> ZCML is purely an add-on package via pyramid_zcml, with its own docs.
> The core Pyramid docs will not cover it, although they might mention it
> in passing.

It sounds like there's actually a third level, "Framework Developer /
Internals Hacker". We've acknowledged that there would be such
people, but we haven't given much thought to what kind of reference
they might want. Of course we can't undertake to write anything like
that now. But we can define the category and its scope, and make a
place to dump unfinished notes on the subject, and transfer to it any
existing doc sections that are at this level. It could go into the
Cookbook as long as it's an obviously separate section. Or we could
make a clone of the Cookbook for it.

There are three particular advantages to having a level of "Framework
Developer Docs", even if it never gets beyond the stage of a
collection of notes. (1) It would reinforce Pyramid's reputation as a
solid base for building higher-level frameworks. (2) It would give
greater transparency to the internals, which would both satisfy
hackers (who would read them) and reassure hacker-wannabes (who may
read them someday, but are glad they exist now). That is essentially
what the mass of Linux kernel docs and related HOWTOs have done. (3)
It would give a place for super-advanced stuff so it isn't cluttering
up the everyday documentation.

--
Mike Orr <slugg...@gmail.com>

[Graham Higgins]

On Wednesday, 8 February 2012 17:35:50 UTC, Iain Duncan wrote:

I'll observe that's a straw man that you've brought to the party; no-one has mentioned any trimming of the docs, simplistically or otherwise.

 

That seems like a pretty clear mention of trimming the docs to get rid of the 'esoteric' material to me. The esoteric material absolutely needs to stay, IMHO. A lot of it what makes Pyramid great to advanced developers. It should just be tucked away better somehow.

I stand corrected, thank you.

I was nearing the end of a detailed broadly-in-agreement response when a stray key fumble caused Chrome to exercise ultimate editorial judgement by junking the lot (I'm learning to loathe Unity with a vengeance).

So... broadly, yeah, what you and Mike wrote is more or less where I am atm. 

There was some early HCI work done on characterising users of computer help systems and this work plays into this situation fairly well. Users can be categorised on: i) frequency of interaction and ii) familiarity with the domain. Each dimension has 3-point nominal scale [low, medium, high], making a 3x3 grid. The results revealed that each combo produces its own set of user task requirements, some of which can be resolved merely by a shift of emphasis in the mode, some of which can only be resolved by a change of mode. It's not something that can be applied precisely, more of a frame for thinking about the issues but it works well with both your and Mike's posts combined.

Nevertheless, Chris' post focused on intermediate developers, that's where he sees a relative weakness in the pedagogical support and that's where he sees part of the three months work going. I think his assessment is correct and I note the intended focus of resource expenditure. The primary mission is an improvement of the pedagogical effectiveness of the Pyramid documentation and there's no a priori reason why this shouldn't also be to the benefit of advanced developers.

It is really useful to have this discussion - it's giving people an opportunity to influence the direction and result of the effort.

Cheers,

Graham.

[Iain Duncan]

Pyramid's use of a ZCA registry is still an internal implementation
detail, and as such isn't really intentionally exposed to the outside
world.  It won't make much sense for the docs to explain how Pyramid
works in terms of ZCA vocabulary such as "adaptation", or even link
heavily to things that explain what adaptation, etc is.  Instead,
explanations of framework hooks and such should just tell them which
Configurator methods to call, just as the docs do now.  Theoretically,
Pyramid may disuse the ZCA in a future major release (although it's
highly unlikely).

ZCML is purely an add-on package via pyramid_zcml, with its own docs.
The core Pyramid docs will not cover it, although they might mention it
in passing.

Now Chris is the BDFL, but I disagree. It is an internal implementation detail, but it is *also* an opportunity for developers to use a very powerful system with very little extra effort, because the registry is already there and populated and usable. I, for one, would be very very disappointed if Pyramid eventually ditched using the ZCA under the hood. It's there, it solves certain classes of hard problems very elegantly. It makes writing extendable applications very easy. I don't see the point in pretending it isn't there. I get that it is being downplayed, I get there is a 'zope stigma' to get over. But honestly, an awful lot of people coming to Pyramid now don't realize that there is this fantastic system under the hood. This was much less the case with the early BFG docs and implementation, and that's what drew me to BFG in many ways. I refuse to believe that I'm not indicative of some class of developer. Maybe a minority, but we're there.

At the end of the day, right now pyramid classes-as-views are ZCA multi-adapters of context and request.  This IS useful to know. And it's very useful to know you can register them with interfaces.  The fact that we can use a separate inheritance hierarchy for classes and interfaces is really handy for us. It's great that you don't *need* to know it, but it's still damn useful to understand and opens up a lot of architectural possibilities. So I realize my voice has very little influence here, but please register it as dissent that the ZCA element of Pyramid should be totally hidden.

thanks

iain

[Iain Duncan]

Configurator methods to call, just as the docs do now.  Theoretically,
Pyramid may disuse the ZCA in a future major release (although it's
highly unlikely).

It might also be worth mentioning that dis-using the ZCA would end a lot of my work for our system, and force us to either stay on a frozen version or fork. I do hope to write cookbook stuff on how and why we use the style we use, so I guess take this as a request to be transparent about that possibility, and perhaps not make that decision unilaterally without community discussion and input. One thing I definitely don't want to do is spend time writing documentation and publishing tools that are then rendered either useless or convoluted to use ( as would be the case if we were telling users to add in their own version of the zca registry. I mean, it would be really really really bad for our work. Please do not treat that decision lightly. 

Thanks

Iain

[Michael Merickel]

This was just a documentation emphasis... Pyramid won't be getting rid of the component registry without a damn good reason.

[Chris McDonough]

On Wed, 2012-02-08 at 17:51 -0600, Michael Merickel wrote:
> This was just a documentation emphasis... Pyramid won't be getting rid
> of the component registry without a damn good reason.
>
> On Wed, Feb 8, 2012 at 5:33 PM, Iain Duncan
> <iaindun...@gmail.com> wrote:
>
> Configurator methods to call, just as the docs
> do now. Theoretically,
> Pyramid may disuse the ZCA in a future major
> release (although it's
> highly unlikely).
>
>
>
> It might also be worth mentioning that dis-using the ZCA would
> end a lot of my work for our system, and force us to either
> stay on a frozen version or fork. I do hope to write cookbook
> stuff on how and why we use the style we use, so I guess take
> this as a request to be transparent about that possibility,
> and perhaps not make that decision unilaterally without
> community discussion and input. One thing I definitely don't
> want to do is spend time writing documentation and publishing
> tools that are then rendered either useless or convoluted to
> use ( as would be the case if we were telling users to add in
> their own version of the zca registry. I mean, it would be
> really really really bad for our work. Please do not treat
> that decision lightly.

In the unlikely case that Pyramid disuses the ZCA for its own internals,
we will certainly make it possible to re-use the ZCA within Pyramid for
end user apps, either via a plugin or a hotwo. I'll be happy to be
transparent about it if we wind up thinking about ditching the ZCA.

But please note that Pyramid has *never* pushed the ZCA as a development
tool. We've been very careful to document it as an implementation
detail; there are a few places today that the ZCA registry API bleeds
out (e.g. registering a traverser, for example), but this was never
meant to signal an intent that a wrapper API on the Configurator might
not become the more "correct" way to do these very few minor things and
the old way (directly accessing the ZCA API) become deprecated.

There's absolutely nothing at all about any web framework that prevents
the ZCA from being used within an application written within that
framework. The fact that both Pyramid and your application happen to
use the same ZCA registry currently is completely orthogonal to one or
the other using it. Please try to mentally separate your application's
use of the ZCA from the framework's. In reality if Pyramid did ditch
the ZCA, the changes required to your application would likely be
extremely minimal unless you're currently using stuff that *is not an
API*, such as querying the registry for registrations *made by Pyramid*.
Don't do that.

- C

[Bruce Coble]

You can count me in for another $50...

Bruce

[Chris McDonough]

On Thu, 2012-02-09 at 16:35 -0800, Bruce Coble wrote:
> You can count me in for another $50...

Thanks!

>
> Bruce

>
>
> --
> You received this message because you are subscribed to the Google
> Groups "pylons-discuss" group.

> To view this discussion on the web visit

> https://groups.google.com/d/msg/pylons-discuss/-/x5nfcGchdj8J.

> To post to this group, send email to pylons-...@googlegroups.com.

> To unsubscribe from this group, send email to pylons-discuss
> +unsub...@googlegroups.com.

[Iain Duncan]

Is there a plan to have a docs page about what's happening with the docs? (or wiki/trac/etc) I'd like to start documenting some of how we work with Pyramid and be able to integrate it better with the Real Docs.

Thanks

Iain

[Blaise Laflamme]

You can start a page on the github pyramid wiki

[Iain Duncan]

On Fri, Feb 10, 2012 at 9:57 AM, Blaise Laflamme <bla...@laflamme.org> wrote:

You can start a page on the github pyramid wiki

What I mean was to ask whether Graham et al would be putting up a roadmap somewhere of their reorg so I can slant my efforts accordingly.

Thanks

Iain

[Arndt Droullier]

Am Freitag, den 10.02.2012, 09:57 -0800 schrieb Blaise Laflamme:
> You can start a page on the github pyramid wiki
>

BTW, will the new website also include user accounts to publish How Tos
or pyramid extensions? Especially a central list of pyramid extensions
was useful.

Arndt.

[Chris McDonough]

The docs overhaul project isn't about a new website, it's just about
overhauling the existing narrative and API docs.

Currently the Cookbook is where to put howtos (you can fork it and add
new howtos via https://github.com/Pylons/pyramid_cookbook). You can
create Pyramid extensions and publish them to PyPI at your will.
"Official" extensions (ones which have good docs and good test coverage,
and have been accepted into the project) are collected at
http://docs.pylonsproject.org/en/latest/docs/pyramid.html#pyramid-add-on-documentation

- C

[Iain Duncan]

The docs overhaul project isn't about a new website, it's just about
overhauling the existing narrative and API docs.

Currently the Cookbook is where to put howtos (you can fork it and add
new howtos via https://github.com/Pylons/pyramid_cookbook). You can
create Pyramid extensions and publish them to PyPI at your will.
"Official" extensions (ones which have good docs and good test coverage,
and have been accepted into the project) are collected at
http://docs.pylonsproject.org/en/latest/docs/pyramid.html#pyramid-add-on-documentation

Is there a guideline anywhere for those standards? I know we'd have a lot of work to do to meet them, and whether or not it turned out to be worth having something become an "official extension", it would behoove us to get our grungy work up to that standard.

thanks

Iain

[Chris McDonough]

Yes, there is. Somewhere. ;-) I wrote it but now cannot find it.
I'll try to find it later this evening and point at it.

- C

[Iain Duncan]

that would be great Chris, thanks.

Iain

[Joe Dallago]

Count me in for $25. I can give it to you at PyCon, if that is not
too late. Otherwise, Paypal or something.

> --
> You received this message because you are subscribed to the Google Groups
> "pylons-discuss" group.

> To post to this group, send email to pylons-...@googlegroups.com.
> To unsubscribe from this group, send email to

> pylons-discus...@googlegroups.com.

[Mike Orr]

On Fri, Feb 10, 2012 at 9:57 AM, Blaise Laflamme <bla...@laflamme.org> wrote:

> You can start a page on the github pyramid wiki

I started a page for the documentation roadmap and user suggestions.

https://github.com/Pylons/pyramid/wiki/Documentation-Roadmap

--
Mike Orr <slugg...@gmail.com>

[Chris McDonough]

On Fri, 2012-02-10 at 13:12 -0800, Mike Orr wrote:
> On Fri, Feb 10, 2012 at 9:57 AM, Blaise Laflamme <bla...@laflamme.org> wrote:
> > You can start a page on the github pyramid wiki
>
> I started a page for the documentation roadmap and user suggestions.
>
> https://github.com/Pylons/pyramid/wiki/Documentation-Roadmap

Excellent, thanks!

- C

>
> --
> Mike Orr <slugg...@gmail.com>
>

[Chris McDonough]

http://docs.pylonsproject.org/en/latest/community/codestyle.html

http://docs.pylonsproject.org/en/latest/community/addons-devenvs.html

- C

[Luciano Ramalho]

On 4 fev, 01:53, Chris McDonough <chr...@plope.com> wrote:
> So this is me asking you for money.  If I can find four other sponsors
> willing to contribute US $1000, I will contribute another $1000, making
> a total of $5000.

That is a great idea, Chris.

I can contribute $100. Suggestion: set up a project on some
crowdfunding site like http://www.fundageek.com/ and you'll have 5K
real quick.

I will state the obvious, but anyway: Graham should make it as easy as
possible for everyone to follow his progress and read the new docs as
it is written so that we can provide timely feedback.

Cheers,

Luciano

[Iain Duncan]

>
>
> that would be great Chris, thanks.

http://docs.pylonsproject.org/en/latest/community/codestyle.html

http://docs.pylonsproject.org/en/latest/community/addons-devenvs.html

Thanks!

Iain

[Iain Duncan]

That is a great idea, Chris.

I can contribute $100. Suggestion: set up a project on some
crowdfunding site like http://www.fundageek.com/ and you'll have 5K
real quick.

+1 on that, kickstarter and it's ilk make it really easy to donate. 

iain

[Chris McDonough]

On Fri, 2012-02-10 at 14:11 -0600, Joe Dallago wrote:
> Count me in for $25. I can give it to you at PyCon, if that is not
> too late. Otherwise, Paypal or something.

Thanks!

I have applied for a kickstarter.com project in the meantime.

- C

[Tarek Ziadé]

On 4 fév, 04:53, Chris McDonough <chr...@plope.com> wrote:
> ...

>
> So this is me asking you for money.  If I can find four other sponsors
> willing to contribute US $1000, I will contribute another $1000, making
> a total of $5000.
>

> Can you convince your company to donate US $1K to this effort?  The
> money would be collected by Agendaless and transfered to Graham as soon
> as we reached our goal.
>

Mozilla will contribute $1000 to help in this effort

Cheers
Tarek

[artee]

Hi

I can contribute $50.
Please add me to the list and tell us how send the money.

Artur Lew

[Chris McDonough]

Wow, thanks a lot!

- C

>
> Cheers
> Tarek
>

[Chris McDonough]

On Mon, 2012-02-13 at 03:58 -0800, artee wrote:
> Hi
>
> I can contribute $50.
> Please add me to the list and tell us how send the money.

Great, thank you!

Still awaiting approval, but with any luck the money will eventually be
collected via a kickstarter.com account.

- C

>
> Artur Lew

>
>
> --
> You received this message because you are subscribed to the Google
> Groups "pylons-discuss" group.

> To view this discussion on the web visit

> https://groups.google.com/d/msg/pylons-discuss/-/d4nvI7Yk0OAJ.

> To post to this group, send email to pylons-...@googlegroups.com.

> To unsubscribe from this group, send email to pylons-discuss
> +unsub...@googlegroups.com.

[Iain Duncan]

Awesome! I was chatting with Yvan Boily (Mozilla privacy/security guru) about Mozilla's use of Pyramid here in Vancouver at the OWASP meetup. Great to hear. =)

iain

[Wayne Witzel III]

Put me down for $100.

[Jonathan Vanasco]

Just wanted to add to this discussion , for potential things to
address in the docs:

The security authorization/authentication stuff is a bit intense.

At first glance, it looks and reads very much like an "enterprise
software" type of system, with a lot of overhead. If I were building
a CMS or a financial / health insurance company - this looks to be on
par with ( if not better than ) most of the huge commercial java
projects out there.

If I were building a dumb social webapp, this is a lot of overkill.

I don't think "dumbing down" is the right approach , but the areas I
see that could be useful are:

1. A nice paragraph or two giving an overview of the scope / style of
Security that is offered , and why you might want to use it. ( even
the first bit of http://readthedocs.org/docs/pyramid/en/1.0-branch/narr/security.html
is too intense for this ).

2. Recommendations for implementing security with concern for the
constant questions on optimization that come up -- things like caching
and database access

3. A note that says "This might be overkill for your application. If
so, here are some techniques that are very lightweight - and while
relatively 'insecure', they might be secure enough for your needs".

[Michael Merickel]

On Wed, Feb 22, 2012 at 11:31 AM, Jonathan Vanasco <jona...@findmeon.com> wrote:

1. A nice paragraph or two giving an overview of the scope / style of
Security that is offered , and why you might want to use it. ( even
the first bit of http://readthedocs.org/docs/pyramid/en/1.0-branch/narr/security.html
is too intense for this ).

Linking to docs for version 1.0 is probably a bad idea. Anyway there was a thought of incorporating http://michael.merickel.org/projects/pyramid_auth_demo/ into the docs in some way if anyone wants to comment on it.

[Benjamin Sims]

Sorry, you mentioned your version of the docs in response to a similar comment that I made and I didn't reply. 

I did find your explanation very helpful in breaking down the explanations into digestible chunks - I'd very much support that yours should be merged into the main documents.

Ben

--

You received this message because you are subscribed to the Google Groups "pylons-discuss" group.

To post to this group, send email to pylons-...@googlegroups.com.

To unsubscribe from this group, send email to pylons-discus...@googlegroups.com.