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 | [EMAIL PROTECTED] | Brisbane, Australia
---------------------------------------------------------------
http://www.boredomandlaziness.org
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
