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 -- 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.
