[Python-Dev] The socket HOWTO

[Steven D'Aprano]

Antoine Pitrou wrote:
> On Mon, 06 Jun 2011 10:33:14 +0200
> "Martin v. Löwis" <martin at v.loewis.de> wrote:
[...]
>> How can you make such claims when several people have indicated that
>> the howto *actually* helped them?
> 
> The point here is that the examples in that document are very poor
> (the only substantial example actually duplicates existing
> functionality - in a sub-optimal manner - without even mentioning the
> existence of said functionality), and the technical explanations are
> nearly non-existent. So I'll happy stand by my claims.

You know, for the amount of discussion about whether or not the doc is 
worth keeping, we probably could have fixed all the problems with it :)

I believe that "status quo wins" is worth applying here. In the absence 
of evidence that the HOWTO is actively harmful, we should keep it.

I'm of two minds whether it should go into the wiki. I would hate for 
the wiki to become the place where bad docs go to die, but on the other 
hand putting it in the wiki may encourage lightweight incremental fixes.

I think the Socket HOWTO is important enough to fix, not throw out. I 
also dislike link-rot, and throwing it out causes link-rot. I'd rather 
see a bunch of concrete bug reports for the HOWTO than just a dismissive 
"throw it out and start again".


> The Python documentation isn't meant to host any potentially helpful
> document, however flawed. We have the Internet for that.

I think it is unfair to dismiss the document as "potentially" helpful 
when a number of people have said that it *actually* did help them.



-- 
Steven