From matt at tplus1.com  Wed Jun  3 18:03:40 2009
From: matt at tplus1.com (Matthew Wilson)
Date: Wed, 3 Jun 2009 12:03:40 -0400
Subject: [Python-authors] first post
Message-ID: <f6f643a20906030903o3294051fjc472f2feffdd4b1e@mail.gmail.com>

Hi --

I have a few fairly popular blog posts with python tutorials

I'd like to contribute these to the main python documentation
repository, but I don't know what to do.

Do I just email in a patch after checking out the main svn repository?
 Is there anything special to do for docs vs code?

Matt



-- 
Matthew Wilson
matt at tplus1.com
http://tplus1.com

From jnoller at gmail.com  Wed Jun  3 18:08:48 2009
From: jnoller at gmail.com (Jesse Noller)
Date: Wed, 3 Jun 2009 12:08:48 -0400
Subject: [Python-authors] first post
In-Reply-To: <f6f643a20906030903o3294051fjc472f2feffdd4b1e@mail.gmail.com>
References: <f6f643a20906030903o3294051fjc472f2feffdd4b1e@mail.gmail.com>
Message-ID: <4222a8490906030908k7ba60141y37cc75d086e84bdb@mail.gmail.com>

You need to sync the source tree, modify the ReST documentation, and
open bugs on bugs.python.org including your patches (unified diff is
fine). More than likely, Georg will respond quickly to any
documentation patches filed.

Email is not the proper place to send patches however

jesse

On Wed, Jun 3, 2009 at 12:03 PM, Matthew Wilson <matt at tplus1.com> wrote:
> Hi --
>
> I have a few fairly popular blog posts with python tutorials
>
> I'd like to contribute these to the main python documentation
> repository, but I don't know what to do.
>
> Do I just email in a patch after checking out the main svn repository?
> ?Is there anything special to do for docs vs code?
>
> Matt
>
>
>
> --
> Matthew Wilson
> matt at tplus1.com
> http://tplus1.com
> _______________________________________________
> Python-authors mailing list
> Python-authors at python.org
> http://mail.python.org/mailman/listinfo/python-authors
>

From doug.hellmann at gmail.com  Wed Jun  3 18:17:59 2009
From: doug.hellmann at gmail.com (Doug Hellmann)
Date: Wed, 3 Jun 2009 12:17:59 -0400
Subject: [Python-authors] first post
In-Reply-To: <f6f643a20906030903o3294051fjc472f2feffdd4b1e@mail.gmail.com>
References: <f6f643a20906030903o3294051fjc472f2feffdd4b1e@mail.gmail.com>
Message-ID: <016D34DF-531D-4A42-8926-A2655F38BA54@gmail.com>


On Jun 3, 2009, at 12:03 PM, Matthew Wilson wrote:

> Hi --
>
> I have a few fairly popular blog posts with python tutorials
>
> I'd like to contribute these to the main python documentation
> repository, but I don't know what to do.
>
> Do I just email in a patch after checking out the main svn repository?
> Is there anything special to do for docs vs code?

According to the core-dev contribution instructions (http://python.org/dev/contributing/ 
) submitting a tracker issue with an attached patch should be all you  
need to do.  I think those types of tickets go to Georg automatically,  
but I'm not sure about that.

Doug


From vasudevram at gmail.com  Wed Jun  3 20:50:43 2009
From: vasudevram at gmail.com (Vasudev Ram)
Date: Thu, 4 Jun 2009 00:20:43 +0530
Subject: [Python-authors] Joined the python-authors list and introducing
	myself
Message-ID: <c958c2e70906031150y7f543c6fs5b9eaa0ebb791203@mail.gmail.com>

Hi python-authors list members,

I'm Vasudev Ram, an independent software developer, trainer and writer.

I work on Python, among other areas. I like Python a lot.

I wrote the xtopdf toolkit in Python; I've also written some articles
before, including one on how to use xtopdf to convert text, CSV, TDV and XLS
formatted content to PDF.

I'm interested in writing articles about Python (and other areas too).

You can see more information about me, including xtopdf and my articles, at
my web site, the URL of which is in my sig below.

Vasudev
---
Dancing Bison Enterprises
Biz: www.dancingbison.com
Google Profile: http://is.gd/tWe3
Blog: jugad2.blogspot.com
xtopdf: fast and easy PDF creation: www.dancingbison.com/products.html
Twitter: @vasudevram
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-authors/attachments/20090604/ce2dbac8/attachment.htm>

From goodger at python.org  Wed Jun  3 20:54:51 2009
From: goodger at python.org (David Goodger)
Date: Wed, 3 Jun 2009 14:54:51 -0400
Subject: [Python-authors] first post
In-Reply-To: <f6f643a20906030903o3294051fjc472f2feffdd4b1e@mail.gmail.com>
References: <f6f643a20906030903o3294051fjc472f2feffdd4b1e@mail.gmail.com>
Message-ID: <4335d2c40906031154t71e3d886k70db4c41070eef32@mail.gmail.com>

On Wed, Jun 3, 2009 at 12:03, Matthew Wilson <matt at tplus1.com> wrote:
> I have a few fairly popular blog posts with python tutorials
>
> I'd like to contribute these to the main python documentation
> repository, but I don't know what to do.
>
> Do I just email in a patch after checking out the main svn repository?
>  Is there anything special to do for docs vs code?

For future reference, the doc-sig at python.org mailing list
(http://mail.python.org/mailman/listinfo/doc-sig) is the right place
to ask such questions, discuss the Python docs, etc.

-- 
David Goodger <http://python.net/~goodger>

From doug.hellmann at gmail.com  Thu Jun 11 20:17:28 2009
From: doug.hellmann at gmail.com (Doug Hellmann)
Date: Thu, 11 Jun 2009 14:17:28 -0400
Subject: [Python-authors] intro and looking for writing tips
Message-ID: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>

Hi, everyone!

I meant to send out an introductory message to the list a few weeks  
back, but have been dealing with home repair issues that couldn't be  
put off.  That's all under control now, though, so I'm ready to get  
things going here.

By way of a quick intro for those who don't know me: I've been working  
with Python since '98-99 (version 1.4).  Right now I am a senior  
developer for Racemi, and our product is a suite of data center  
automation tools (server, infrastructure, and image management) built  
using Python 2.6.  As far as writing experience, I blog and have  
written for Python Magazine, and last year I was Editor in Chief.   
I've also done a few technical reviews for books.

As I've said in the past, I wanted to get this list going as a way of  
building a stronger group of writers and editors within the Python  
community.  I hope we can trade advice and find collaborators for new  
and recurring projects.

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?

So far I've been approaching it as I do programming: Reading a lot of  
other people's writing and looking for projects to let me practice my  
own.  I've also tried to revisit some of my "earlier" work to study it  
and look for ways to improve.  If you're an author, what did you do to  
improve your work when you were starting out?  What actually worked,  
and what was a waste of time?

Doug


From mdoar at pobox.com  Fri Jun 12 00:46:04 2009
From: mdoar at pobox.com (Matt Doar)
Date: Thu, 11 Jun 2009 15:46:04 -0700
Subject: [Python-authors] intro and looking for writing tips
In-Reply-To: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
Message-ID: <7708e5010906111546w7fcffd42lb93d2684b68453ec@mail.gmail.com>

I've been writing technically for about 20 years now (papers, reviews, a
Ph.D. thesis, various articles, a book for O'Reilly etc) and I still think
"you need the determination to get it done" is the most important advice.
98% perspiration and all that. Then you really have to care whether people
understand what you are saying, and of course you need basic proficiency in
some language (I'm starting at the beginning). Along the way I've been
helped by:

   1. Thinking who I'm writing for.
   2. Creating an outline, at two levels if necessary, of the specific
   contents of what I want to communicate
   3. Reviewing the outline with others
   4. Filling in the outline.
   5. Proof-reading, copy editing adds a level of polish.

Sometimes I write down a list of things that have irritated me in other
articles or books to make sure I don't forget to avoid them.
O'Reilly has a general guide for book authors:
http://oreilly.com/oreilly/author/index.html

All very general, and I'm still learning as I go.

~Matt

On Thu, Jun 11, 2009 at 11:17 AM, Doug Hellmann <doug.hellmann at gmail.com>wrote:

> Hi, everyone!
>
> I meant to send out an introductory message to the list a few weeks back,
> but have been dealing with home repair issues that couldn't be put off.
>  That's all under control now, though, so I'm ready to get things going
> here.
>
> By way of a quick intro for those who don't know me: I've been working with
> Python since '98-99 (version 1.4).  Right now I am a senior developer for
> Racemi, and our product is a suite of data center automation tools (server,
> infrastructure, and image management) built using Python 2.6.  As far as
> writing experience, I blog and have written for Python Magazine, and last
> year I was Editor in Chief.  I've also done a few technical reviews for
> books.
>
> As I've said in the past, I wanted to get this list going as a way of
> building a stronger group of writers and editors within the Python
> community.  I hope we can trade advice and find collaborators for new and
> recurring projects.
>
> 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?
>
> So far I've been approaching it as I do programming: Reading a lot of other
> people's writing and looking for projects to let me practice my own.  I've
> also tried to revisit some of my "earlier" work to study it and look for
> ways to improve.  If you're an author, what did you do to improve your work
> when you were starting out?  What actually worked, and what was a waste of
> time?
>
> Doug
>
> _______________________________________________
> Python-authors mailing list
> Python-authors at python.org
> http://mail.python.org/mailman/listinfo/python-authors
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-authors/attachments/20090611/73388f7c/attachment.htm>

From aahz at pythoncraft.com  Fri Jun 12 00:52:34 2009
From: aahz at pythoncraft.com (Aahz)
Date: Thu, 11 Jun 2009 15:52:34 -0700
Subject: [Python-authors] intro and looking for writing tips
In-Reply-To: <7708e5010906111546w7fcffd42lb93d2684b68453ec@mail.gmail.com>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
	<7708e5010906111546w7fcffd42lb93d2684b68453ec@mail.gmail.com>
Message-ID: <20090611225234.GB22982@panix.com>

On Thu, Jun 11, 2009, Matt Doar wrote:
>
> I've been writing technically for about 20 years now (papers, reviews, a
> Ph.D. thesis, various articles, a book for O'Reilly etc) and I still think
> "you need the determination to get it done" is the most important advice.
> 98% perspiration and all that. 

While that's true, it's more complicated than that.  Different people who
have different emotional makeups can find that it takes them more or less
emotional effort to produce the same amount of determination.  For
example, I had (technically still have) a contract to write _Effective
Python_, but I hit a wall and was unable to do the work.  However, I was
able to do my fair share of writing with a co-author for _Python for
Dummies_. [*]

If you're the kind of person who can't work by yourself, you won't be
able to write a book unless you have a very strong support network.


[*] As the joke goes, when multiple people write a book together, each
person needs to contribute 80% of the effort.
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"If you don't know what your program is supposed to do, you'd better not
start writing it."  --Dijkstra

From aahz at pythoncraft.com  Fri Jun 12 03:48:04 2009
From: aahz at pythoncraft.com (Aahz)
Date: Thu, 11 Jun 2009 18:48:04 -0700
Subject: [Python-authors] intro and looking for writing tips
In-Reply-To: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
Message-ID: <20090612014804.GB28545@panix.com>

On Thu, Jun 11, 2009, 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?

Read K&R.  It remains one of the best examples ever of condensed
technical writing that works as both a tutorial and a reference.  If
nothing else, you'll learn C programming, which is still useful.  ;-)
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"Many customs in this life persist because they ease friction and promote
productivity as a result of universal agreement, and whether they are
precisely the optimal choices is much less important." --Henry Spencer

From willg at bluesock.org  Fri Jun 12 05:32:15 2009
From: willg at bluesock.org (will)
Date: Thu, 11 Jun 2009 23:32:15 -0400
Subject: [Python-authors] intro and looking for writing tips
In-Reply-To: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
Message-ID: <4A31CC3F.2070106@bluesock.org>

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've done a bunch of technical reviews recently, lots of documentation 
over the years and some book writing for books that were mild failures 
at best over a decade ago.

I keep thinking about writing for Python magazine, but haven't done it 
yet.  I also keep thinking about writing a book on project management 
for Python projects and self-publishing, but haven't done that yet either.

As an aside, the PMOTW is fantastic.  You should talk those articles, 
edit them a bit (if they need editing), toss them into Sphinx, generate 
a PDF and sell it on Lulu or some other self-publishing site if someone 
else hasn't done it already.  If you need help, I'd be happy to help.

/will

From doug.hellmann at gmail.com  Fri Jun 12 17:25:15 2009
From: doug.hellmann at gmail.com (Doug Hellmann)
Date: Fri, 12 Jun 2009 11:25:15 -0400
Subject: [Python-authors] intro and looking for writing tips
In-Reply-To: <20090611225234.GB22982@panix.com>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
	<7708e5010906111546w7fcffd42lb93d2684b68453ec@mail.gmail.com>
	<20090611225234.GB22982@panix.com>
Message-ID: <A8412BD1-E76B-493E-A4F0-71EC67425904@gmail.com>


On Jun 11, 2009, at 6:52 PM, Aahz wrote:

> On Thu, Jun 11, 2009, Matt Doar wrote:
>>
>> I've been writing technically for about 20 years now (papers,  
>> reviews, a
>> Ph.D. thesis, various articles, a book for O'Reilly etc) and I  
>> still think
>> "you need the determination to get it done" is the most important  
>> advice.
>> 98% perspiration and all that.
>
> While that's true, it's more complicated than that.  Different  
> people who
> have different emotional makeups can find that it takes them more or  
> less
> emotional effort to produce the same amount of determination.  For
> example, I had (technically still have) a contract to write _Effective
> Python_, but I hit a wall and was unable to do the work.  However, I  
> was
> able to do my fair share of writing with a co-author for _Python for
> Dummies_. [*]
>
> If you're the kind of person who can't work by yourself, you won't be
> able to write a book unless you have a very strong support network.

What sort of "support network" do you think is most valuable?  Do you  
mean personally, like a spouse or SO giving you space and time, or  
peers providing advice and commentary?

Doug


From doug at hellfly.net  Fri Jun 12 17:26:37 2009
From: doug at hellfly.net (Doug Hellmann)
Date: Fri, 12 Jun 2009 11:26:37 -0400
Subject: [Python-authors] intro and looking for writing tips
In-Reply-To: <20090612014804.GB28545@panix.com>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
	<20090612014804.GB28545@panix.com>
Message-ID: <B7880A06-1432-4C84-8D24-B7785C3B30B9@hellfly.net>


On Jun 11, 2009, at 9:48 PM, Aahz wrote:

> On Thu, Jun 11, 2009, 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?
>
> Read K&R.  It remains one of the best examples ever of condensed
> technical writing that works as both a tutorial and a reference.  If
> nothing else, you'll learn C programming, which is still useful.  ;-)

Wow, that brings back memories.  I think K&R was simultaneously the  
thinnest and most valuable book I had in college.  It's a tough  
standard to live up to.

Doug


From doug.hellmann at gmail.com  Fri Jun 12 17:22:25 2009
From: doug.hellmann at gmail.com (Doug Hellmann)
Date: Fri, 12 Jun 2009 11:22:25 -0400
Subject: [Python-authors] intro and looking for writing tips
In-Reply-To: <7708e5010906111546w7fcffd42lb93d2684b68453ec@mail.gmail.com>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
	<7708e5010906111546w7fcffd42lb93d2684b68453ec@mail.gmail.com>
Message-ID: <C09E15C7-C796-4BC7-88EB-96E980A9B38F@gmail.com>


On Jun 11, 2009, at 6:46 PM, Matt Doar wrote:

>
> I've been writing technically for about 20 years now (papers,  
> reviews, a Ph.D. thesis, various articles, a book for O'Reilly etc)  
> and I still think "you need the determination to get it done" is the  
> most important advice. 98% perspiration and all that.

I definitely agree with that.  I'm still learning to estimate the  
amount of time writing different lengths and types of work take.  
Usually it's more than I think. :-)

> Then you really have to care whether people understand what you are  
> saying, and of course you need basic proficiency in some language  
> (I'm starting at the beginning). Along the way I've been helped by:
> Thinking who I'm writing for.
> Creating an outline, at two levels if necessary, of the specific  
> contents of what I want to communicate
> Reviewing the outline with others
> Filling in the outline.
> Proof-reading, copy editing adds a level of polish.
How much benefit do you think you get from feedback from an editor/ 
reviewer looking over an early draft vs. something you've revised once  
or twice yourself?

> Sometimes I write down a list of things that have irritated me in  
> other articles or books to make sure I don't forget to avoid them.

That's an interesting idea, I haven't heard that one before. I guess  
that's part of the point of doing a lot of reading, though, isn't it?

Doug

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-authors/attachments/20090612/8cf35440/attachment.htm>

From doug.hellmann at gmail.com  Fri Jun 12 17:34:58 2009
From: doug.hellmann at gmail.com (Doug Hellmann)
Date: Fri, 12 Jun 2009 11:34:58 -0400
Subject: [Python-authors] expert-level books,
	was Re: intro and looking for writing tips
In-Reply-To: <4A31CC3F.2070106@bluesock.org>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
	<4A31CC3F.2070106@bluesock.org>
Message-ID: <F4F66E0B-CF1D-4A4D-8446-42E95BFF875A@gmail.com>


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?

That brings up another question I've been thinking about for some  
time:  I've noticed a lot of Python-related books that seem to be  
aimed at entry or mid-level programmers.  Obviously that's a big  
group, and one hungry for opportunities to learn more.  What explains  
the apparent lack of books for the "expert" level audience, though?   
Do more experienced programmers not buy as many books, or is it just  
that they're a harder audience to address?  Or am I completely off- 
base, and just unaware of the wide selection of more advanced titles  
available?

I know we have a few publishers on the list now, would anyone care to  
comment?  Is this an unexplored area with room for growth, or is the  
well dry?

> I keep thinking about writing for Python magazine, but haven't done  
> it yet.

I'm sure Brandon would be happy to entertain a proposal for an  
article, you should contact him directly.

> 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?

> As an aside, the PMOTW is fantastic.  You should talk those  
> articles, edit them a bit (if they need editing), toss them into  
> Sphinx, generate a PDF and sell it on Lulu or some other self- 
> publishing site if someone else hasn't done it already.  If you need  
> help, I'd be happy to help.

Oh, yeah, I'm in love with Sphinx.  See http://www.doughellmann.com/PyMOTW/PyMOTW-1.91.1.pdf 
  -- it needs a lot of polishing and weeding before it's publishable,  
though.

Doug


From willg at bluesock.org  Fri Jun 12 18:50:13 2009
From: willg at bluesock.org (will)
Date: Fri, 12 Jun 2009 12:50:13 -0400
Subject: [Python-authors] expert-level books,
 was Re: intro and looking for writing tips
In-Reply-To: <F4F66E0B-CF1D-4A4D-8446-42E95BFF875A@gmail.com>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>	<4A31CC3F.2070106@bluesock.org>
	<F4F66E0B-CF1D-4A4D-8446-42E95BFF875A@gmail.com>
Message-ID: <4A328745.5000403@bluesock.org>

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

From mdoar at pobox.com  Fri Jun 12 18:59:05 2009
From: mdoar at pobox.com (Matt Doar)
Date: Fri, 12 Jun 2009 09:59:05 -0700
Subject: [Python-authors] intro and looking for writing tips
In-Reply-To: <B7880A06-1432-4C84-8D24-B7785C3B30B9@hellfly.net>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com> 
	<20090612014804.GB28545@panix.com>
	<B7880A06-1432-4C84-8D24-B7785C3B30B9@hellfly.net>
Message-ID: <7708e5010906120959k40d1a18av863b4daf81e9c510@mail.gmail.com>

On Fri, Jun 12, 2009 at 8:26 AM, Doug Hellmann <doug at hellfly.net> wrote:

>
> (snip)
>  Wow, that brings back memories.  I think K&R was simultaneously the
> thinnest and most valuable book I had in college.  It's a tough standard to
> live up to.
>

That reminds me that many of the books I admire the most are fewer than 300
pages. It's a good way to avoid "fluffy" technical books if that's not your
thing - just choose the thinner of two choices.

~Matt


>
> Doug
>
>
> _______________________________________________
> Python-authors mailing list
> Python-authors at python.org
> http://mail.python.org/mailman/listinfo/python-authors
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-authors/attachments/20090612/fac4603d/attachment.htm>

From aahz at pythoncraft.com  Fri Jun 12 19:53:45 2009
From: aahz at pythoncraft.com (Aahz)
Date: Fri, 12 Jun 2009 10:53:45 -0700
Subject: [Python-authors] intro and looking for writing tips
In-Reply-To: <A8412BD1-E76B-493E-A4F0-71EC67425904@gmail.com>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>
	<7708e5010906111546w7fcffd42lb93d2684b68453ec@mail.gmail.com>
	<20090611225234.GB22982@panix.com>
	<A8412BD1-E76B-493E-A4F0-71EC67425904@gmail.com>
Message-ID: <20090612175345.GA6494@panix.com>

On Fri, Jun 12, 2009, Doug Hellmann wrote:
> On Jun 11, 2009, at 6:52 PM, Aahz wrote:
>> 
>> If you're the kind of person who can't work by yourself, you won't be
>> able to write a book unless you have a very strong support network.
>
> What sort of "support network" do you think is most valuable?  Do you  
> mean personally, like a spouse or SO giving you space and time, or peers 
> providing advice and commentary?

Yes.  ;-)  Those are not questions that can be answered in a vacuum; the
whole point is that each person's needs are different.  Moreover,
building a support network takes effort, and the kinds of support readily
available to you is doubtless different from mine, and it may well be
worth trading off some quality in the network for a larger network or
less time/energy spent building your network.
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"Many customs in this life persist because they ease friction and promote
productivity as a result of universal agreement, and whether they are
precisely the optimal choices is much less important." --Henry Spencer

From doug.hellmann at gmail.com  Fri Jun 12 19:57:28 2009
From: doug.hellmann at gmail.com (Doug Hellmann)
Date: Fri, 12 Jun 2009 13:57:28 -0400
Subject: [Python-authors] expert-level books,
	was Re: intro and looking for writing tips
In-Reply-To: <4A328745.5000403@bluesock.org>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>	<4A31CC3F.2070106@bluesock.org>
	<F4F66E0B-CF1D-4A4D-8446-42E95BFF875A@gmail.com>
	<4A328745.5000403@bluesock.org>
Message-ID: <C80CC940-2B11-407F-9960-6C91763A5209@gmail.com>


On Jun 12, 2009, at 12:50 PM, will wrote:

> Doug Hellmann wrote:
>> On Jun 11, 2009, at 11:32 PM, will wrote:
>>> Doug Hellmann wrote:
>>>>
>>> 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.

Ah, I understand what you mean now.

> 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

That sounds like a good collection of information to have in one  
place.  Have you seen Tarek's book, Expert Python Programming?  It  
covers some of those topics, but not all, IIRC.

> 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.

Yes, I'm keeping an eye on that to integrate it with the PyMOTW site.   
I'm happy with Disqus, but per-paragraph commentary would be helpful.

Doug


From willg at bluesock.org  Fri Jun 12 20:33:13 2009
From: willg at bluesock.org (will)
Date: Fri, 12 Jun 2009 14:33:13 -0400
Subject: [Python-authors] expert-level books,
 was Re: intro and looking for writing tips
In-Reply-To: <C80CC940-2B11-407F-9960-6C91763A5209@gmail.com>
References: <E3F854FC-9CE4-4A0E-9FDB-0C398A50704E@gmail.com>	<4A31CC3F.2070106@bluesock.org>	<F4F66E0B-CF1D-4A4D-8446-42E95BFF875A@gmail.com>	<4A328745.5000403@bluesock.org>
	<C80CC940-2B11-407F-9960-6C91763A5209@gmail.com>
Message-ID: <4A329F69.5020406@bluesock.org>

Doug Hellmann wrote:
> That sounds like a good collection of information to have in one place.  
> Have you seen Tarek's book, Expert Python Programming?  It covers some 
> of those topics, but not all, IIRC.

I did read his book and it has its moments in regards to this particular 
material, but I think it needed to be more comprehensive.  For one 
thing, it sorely lacks "where to get more information" material.  The 
book isn't focused on project infrastructure and he probably had limited 
space to cover things, so I don't mean to imply that his book sucks.

Grig and Titus (and others) cover testing in their blogs (and other 
places) pretty heavily.  I'd definitely use that as resource material 
and "where to get more information" links.  I've also seen Python 
Magazine articles that cover some of the material, too.

I'd be interested in knowing whether other books, articles, blogs, etc 
cover this material well.

/will