What to do next for 2.6?

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

What to do next for 2.6?

A.M. Kuchling
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?

--amk
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: What to do next for 2.6?

Ron Adam


A.M. Kuchling wrote:
> 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?

I'm presuming you are referring to content related items, but I fugures it
doesn't hurt to ask.


A while back I wrote a patch to enhance pydoc.

      http://bugs.python.org/issue2001


I figured it would need to wait until 2.7/3.1, is
there any chance of getting it in before then?


I probably need to updated it again so it will apply properly as there has
been other fixes/patches to pydoc.

Ron
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: What to do next for 2.6?

Laura Creighton-2
In reply to this post by A.M. Kuchling
In a message of Sun, 31 Aug 2008 14:22:04 EDT, "A.M. Kuchling" writes:

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

What is the status of the tutorial?

Laura
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: What to do next for 2.6?

Georg Brandl-2
In reply to this post by A.M. Kuchling
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.

cheers,
Georg

--
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: 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   |   [hidden email]   |   Brisbane, Australia
---------------------------------------------------------------
            http://www.boredomandlaziness.org
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: What to do next for 2.6?

Ron Adam
In reply to this post by Ron Adam

The patch is updated for 2.6.

      http://bugs.python.org/issue2001

Ron



Ron Adam wrote:

>
>
> A.M. Kuchling wrote:
>> 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?
>
> I'm presuming you are referring to content related items, but I fugures
> it doesn't hurt to ask.
>
>
> A while back I wrote a patch to enhance pydoc.
>
>      http://bugs.python.org/issue2001
>
>
> I figured it would need to wait until 2.7/3.1, is
> there any chance of getting it in before then?
>
>
> I probably need to updated it again so it will apply properly as there
> has been other fixes/patches to pydoc.
>
> Ron
> _______________________________________________
> Doc-SIG maillist  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig