[pydotorg-www] Hiring a tech writer
steve at holdenweb.com
Wed Apr 21 20:26:45 CEST 2010
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.
> 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.
This is discussing what type of bricks to use when we don't even know
what type of building is yet required.
Happens all the time with techies, but that doesn't make it the right
way to proceed.
Steve Holden +1 571 484 6266 +1 800 494 3119
See PyCon Talks from Atlanta 2010 http://pycon.blip.tv/
Holden Web LLC http://www.holdenweb.com/
UPCOMING EVENTS: http://holdenweb.eventbrite.com/
More information about the pydotorg-www