[Python-authors] expert-level books, was Re: intro and looking for writing tips

[will]

Doug Hellmann wrote:
> 
> On Jun 11, 2009, at 11:32 PM, will wrote:
> 
>> Doug Hellmann wrote:
>>> I'm fairly new to writing and still looking for ways to improve, so 
>>> I'll start off with a couple of questions from that perspective: What 
>>> books or articles have had an impact on your writing style?  What 
>>> advice would you give a new writer?
>>
>> I'm a big fan of the Little Schemer series.  Dive Into Python is 
>> Little Schemer-like in some ways--I liked that book.
>>
>> I tend to like books that are heavier on technical specifics and 
>> details and light on reader-pampering.  Reader-pampering is all the 
>> fluff where the author tells you it's not hard to understand this 
>> stuff and as soon as you read the next paragraph it'll all be clear 
>> and how the author had a tough time understanding it the first time, 
>> too, so you shouldn't feel bad...  I find that tedious.
> 
> I do too, but I assume there's at least some segment of the reading 
> population that finds it comforting.  Otherwise we wouldn't still see 
> it, right?

I cynically believe that the reason there's so much of it is that it's 
easier to write and fills pages.  Having said that, I'm sure there are 
good uses of it that are helpful.  Also "reader-pampering" is a snooty 
way to refer to it, but I couldn't think of anything else at the time.


>> I also keep thinking about writing a book on project management for 
>> Python projects and self-publishing, but haven't done that yet either.
> 
> That's an interesting idea.  Can you talk a little about how you would 
> make it Python-centric?

"Project management" might be the wrong term to use here.  I'm talking 
less about estimates, schedules, design documents and that side of 
project management and more about directory structures, required files, 
licenses, testing, packaging, deployment, ...  It's a book that would 
walk through the important project infrastructure parts, the questions 
you need to be asking, choices available, how to set up the scaffolding, 
  ...  Maybe "project infrastructure" is a better term to use.

I've been tossing this around after working on Cheesecake and seeing a 
lot of fledgling Python projects (including my own) start "wrong".  The 
problem with starting wrong is that it's often a pain in the ass to 
correct the issues down the road.

At a high level, it'd probably have the following parts:

1. starting a new project, directory structures, important files

2. licensing and copyright, what questions to be thinking about, where 
to go for more information, statistics from Cheeseshop

3. codifying project standards like code style

4. picking one or more testing systems, setting up the scaffolding

5. setting up localization and internationalization

6. picking one or more documentation systems, setting up the scaffolding

7. packaging, deployment and releases


I've been tossing it around but haven't embarked on anything yet.  I'd 
write it with Sphinx as a web-site and when it was done build a PDF and 
sell it on Lulu.

As an aside, there's a GSoC project this year to add per-paragraph 
comment support to Sphinx-built sites:

http://mail.python.org/pipermail/python-dev/2009-May/089798.html

I'm really looking forward to that.

/will