[pydotorg-www] Hiring a tech writer
mfoord at python.org
Wed Apr 21 20:52:34 CEST 2010
On 21/04/2010 19:58, Carl Karsten wrote:
> On Wed, Apr 21, 2010 at 11:30 AM, Aahz<aahz at pythoncraft.com> wrote:
>> On Wed, Apr 21, 2010, skip at pobox.com wrote:
>>> - I wonder if the PSF might consider funding a competent technical
>>> writer with essentially no programming experience to learn the
>>> language and produce a good tutorial aimed at complete novices.
>> If you're serious about this, I can recommend my co-author of Python for
>> Dummies. ;-) (That's a smiley, yes, but it's a serious recommendation;
>> not sure if Stef would be interested, though -- once may have been
>> enough. Stef used to work at Apple, so she's familiar with the "this is
>> a mouse" level of writing.)
> I came up with a progression of about 100 python command line examples
> to take someone from 0-60 in about 2 hours. It assumes they know how
> to program in some other language so that they are familiar with
> datatypes, loops, branching, functions, etc. I did a practice run
> though of cut/pasting each example into the>>> prompt and giving a
> 30-60 second description of what it was about. It took 2.5 hours,
> which included some "what should I say about this?" I think with some
> refinement it could be done in 1.5 hours.
This would be very suitable for Try Python. It presents a pane on the
left side with the Python tutorial. Interactive interpreters are syntax
highlighted with a button to execute them in the interactive interpreter
on the right - which displays the results and can be experimented with
as a normal interactive interpreter.
If you could send the examples to me. preferably with eStructured Text
introductions / explanations between the interactive examples, then I
can add them as a new section on Try Python (with credits of course).
All the best,
> I think the format lends itself to a 2nd version that assumes the
> person has been working with Python, but never seriously learned it
> (like someone who has moved from PHP to Django.) It would be the
> exact same content, only spend much less time verbal description.
> Back to the tutorial: I think it would work, and could be very
> visually appealing.
> What I envision:
> a web page of 10 or 20 commands with some web too oh! buttons:
>>>> "hello world"
>>>> print( "hello world" )
> [show result][quick description][advanced]>>>"hello world"
> [show result][quick description][advanced]>>>print("hello world")
> ...>>>print( 123 )
> clicking the buttons would unfold to:
>>>> "hello world"
> "hello world"
> This shows the REP loop. If the command returns something other than
> None, a printable representation is displayed. This makes the>>>
> prompt a great place to interactively experiment. This is not how a
> typical program will display output.
> The "printable representation" is determined by calling the objects
> .__repr__() method. Exactly what is returned is up to the discretion
> of the programmer who coded the class the object inherits from. You
> will find that most things in the Python Standard Library return a
> reasonable value.
> (complete details:
> http://docs.python.org/reference/datamodel.html#object.__repr__ )
>>>> print("Hello world!")
> Hello world!
> This is how programs can display output to the console. (something
> about gui, web and other outputs so the person does not think STDOUT
> is all there is.)
> The print command calls the objects .__str__() method and sends the
> result to stdout. __str__() defaults to __repr__() or returns
> something human readable.
> With lots of links so that the student never needs to google.
> I also think it might work to have the commands stuffed into something
> like http://codepad.org "online compiler/interpreter" So that the
> student can tweak the example and see what happens. yes, they could
> download/install python, but that is a barrier I want to avoid.
> There are a few other Chicago folk that I bet would be interested in
> this. some are professors.
> I am sensing a wiki like approach. more later, I need to get to work.
More information about the pydotorg-www