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, [email protected] (Chris McDonough) pronounced:
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
--steve
--
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.
