[Doc-SIG] What to do next for 2.6?

[Nick Coghlan]

Georg Brandl wrote:
> A.M. Kuchling schrieb:
>> This weekend I made a final revision pass over the 2.6 "What's New"
>> document and am now finished with it (barring any small corrections or
>> omissions that come in).
>>
>> What should I do now with my Python doc time?  Georg, do you have any
>> suggestions?  I could start reading through one of the manuals from
>> end-to-end or go through the bug tracker for doc items.  Are there any
>> writing-related tasks you've been meaning to do before 2.6final?
> 
> There is one thing I've been putting off for quite a long time :)
> 
> Basically, the builtin types aren't documented well. The
> /library/stdtypes document is too long and not structured in a good
> fashion. Also, signatures for the constructors are documented in
> /library/functions which is not wrong but not satisfying either.
> Also, the type hierarchy in the "data model" section from the lang.
> ref. has overlaps with that section. For example, both document some
> special methods, both document the built-in types, etc.
> 
> I would like to rename the lang. reference to "Core Python language".
> This document would then contain the language spec, ideally enhanced with
> some examples for those not liking having EBNF thrown into their face,
> the "data model" section with all its customization docs, and the content
> on built-in functions and types, all special methods and type methods
> properly documented etc. (e.g. I think some new float methods aren't
> documented yet).
> 
> This is a large task, and I don't want to burden it on you. In my opinion
> it will make the Python documentation structure easier to grasp. I don't
> know how much time you have; I've never found enough of it to start.

Along those lines, I plan to spend my Python time after 2.6/3.0 are out
on an odf2rest converter for the user reference that's currently sitting
in the sandbox. Even if we don't end up using that document as-is (it's
a bit too dated at the moment for that to be a possibility anyway), I
think it will provide useful input to any large-scale additions
(particularly those targeting a middle ground between the tutorial and
the language reference in regards to the language statements and the
builtins).

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------
            http://www.boredomandlaziness.org