[pydotorg-www] Hiring a tech writer

[Carl Karsten]

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.


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")
... >>>123
... >>>print( 123 )
... >>>['hello',123,'world','see?']

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.

-- 
Carl K