[Python-Dev] Documenting [C]Python's Internals

[Michael Foord]

On 21/05/2010 13:42, Lie Ryan wrote:
> On 05/21/10 15:18, Yaniv Aknin wrote:
>    
>> I would if I were qualified, but I an mot. One way to get people to help
>>      
>>> with details is to publish mistakes. This happens all the time on
>>> python-list ;-). Pre-review would be nice though.
>>>
>>>        
>> I don't mind so much the 'humiliation' of published mistakes, but since I
>> want this to be perceived as reference grade material, I prefer pre-review.
>> Yesterday my first mistake was found (ugh), I published an 'Errata Policy'
>> and will stick to it from now on (see the blog itself for details of the
>> mistake). Thankfully, I've been approached already about pre-review, we'll
>> see how this develops (this doesn't mean other people can't also offer
>> themselves, six eyeballs are better than four).
>>      
> How about a separate blog (or wiki) for alpha-quality articles? After an
> article is written, it is first posted to the alpha blog, and after some
> time and eyeballs, moved to the original blog. Of course with an open
> comment system, so people can easily suggest corrections.
>    

Separate blog is confusing I think - you then duplicate your content and 
people are just as likely to be referred to the "alpha quality" version 
as the final version.

Just publish and improve the articles based on feedback - I think your 
current approach with an established errata policy is well beyond what 
most people do or expect. When you have established the sort of coverage 
of the topic you are aiming for you can then take your blog articles, 
along with all feedback, and turn them into documentation.

All the best,

Michael

> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk
>    


-- 
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/blog

READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.