classification
Title: Desire python.org documentation link to user contribution wiki (per function)
Type: enhancement Stage:
Components: Documentation Versions: Python 3.0, Python 3.1, Python 3.2, Python 2.7, Python 2.6
process
Status: closed Resolution: later
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: georg.brandl, keenethery, nnorwitz
Priority: normal Keywords:

Created on 2009-08-06 17:49 by keenethery, last changed 2009-08-24 22:29 by keenethery. This issue is now closed.

Messages (8)
msg91373 - (view) Author: kee nethery (keenethery) Date: 2009-08-06 17:49
Proposal: For each permalink headline in the official documentation, 
link to a wiki page specific to that headline. Allow users to easily 
view and contribute comments and examples around that specific 
documentation headline. For example:
http://docs.python.org/reference/lexical_analysis.html#string-literal-
concatenation
would have an auto-generated link in the main docs of (for example):
http://wiki.docs.python.org/2.6.2#reference#lexical_analysis.html#string
-literal-concatenation
Easy to create, self administering, perhaps valuable to new users, 
completely unofficial.

Newbies need examples, lots of examples. Newbies have noob questions 
about things they are stumbling across that experienced users have 
forgotten was once confusing. For experienced users that knowledge is 
now part of their Python DNA. According to people on the "python-list" 
other languages have wiki style user contribution areas that allow 
newbies to document the things they found confusing (and the answers) 
and to provide lots of code examples. Periodically this newbie 
information is rolled back into the official mainline docs. Requiring 
newbies to join this tracking system and to submit bugs is just way to 
complex for something that is now trivial to do with a wiki and it 
obviously causes the new user contributions to be pretty non-existent. 
Python would be a much easier language to learn if newbies could easily 
contribute through the main documentation web site.
msg91375 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-08-06 17:56
This is already in planning; Sphinx will grow a webapp system that also
allows suggestions for changes.
msg91389 - (view) Author: kee nethery (keenethery) Date: 2009-08-06 21:56
Georg,
So there will be a link next to each numbered section in the  
documentation that links to a user editable wiki page about that  
section?
That will be highly useful. Glad to hear it. I know I'd like to  
contribute the gotchas I was confused by and the sample code snippets  
that solved a specific generic problem. Having more sample code linked  
from each numbered section in the docs would make my life easier when  
trying to learn Python.
Kee Nethery

On Aug 6, 2009, at 10:56 AM, Georg Brandl wrote:

>
> Georg Brandl <georg@python.org> added the comment:
>
> This is already in planning; Sphinx will grow a webapp system that  
> also
> allows suggestions for changes.
>
> ----------
> resolution:  -> later
> status: open -> closed
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue6660>
> _______________________________________

-------------------------------------------------
I check email roughly 2 to 3 times per business day.
Kagi main office: +1 (510) 550-1336
msg91390 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-08-06 22:38
There will be comments for each function/class etc., as well as a
feature to suggest a change for the proper text of a section.
msg91406 - (view) Author: kee nethery (keenethery) Date: 2009-08-07 15:53
awesome. looking forward to it.
Kee

On Aug 6, 2009, at 3:38 PM, Georg Brandl wrote:

>
> Georg Brandl <georg@python.org> added the comment:
>
> There will be comments for each function/class etc., as well as a
> feature to suggest a change for the proper text of a section.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue6660>
> _______________________________________

-------------------------------------------------
I check email roughly 2 to 3 times per business day.
Kagi main office: +1 (510) 550-1336
msg91476 - (view) Author: kee nethery (keenethery) Date: 2009-08-11 15:17
Is there anything I can do to help this happen? Am thinking that these  
are the steps to the process.

1. Create wiki.docs.python.org using the wiki setup template already  
used by wiki.python.org.
2. Lock page creation except for one specific account.
3. Create a template wiki page that has all the subsections desired  
(one per language version)
4. Grab all the existing docs for say version 2.5 moving forward, and  
at each perma-link, add a user contributions wiki link.
5. Keep track of all the user contribution wiki links
6. spin through the list of links and generate all the empty user  
contribution wiki pages.
7. release the docs with the new user contributions wiki links.

I'm not a wiki expert but I'd be happy to build the thing that creates  
each user contribution wiki link in the docs. Then I could pass the  
modified document files back to you. You could verify they are as  
desired. Once that looks good I could have code that spins through the  
links and creates the pages in the wiki.

Kee Nethery

> From: Georg Brandl <report@bugs.python.org>
> Date: August 6, 2009 3:38:33 PM PDT
> To: kee@kagi.com
> Subject: [issue6660] Desire python.org documentation link to user  
> contribution wiki (per function)
> Reply-To: Python tracker <report@bugs.python.org>
>
>
> Georg Brandl <georg@python.org> added the comment:
>
> There will be comments for each function/class etc., as well as a
> feature to suggest a change for the proper text of a section.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue6660>
> _______________________________________
msg91931 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-08-24 17:26
At the moment, I still have to review and merge the SoC branch, so don't
expect visible changes to happen within a few weeks.
msg91944 - (view) Author: kee nethery (keenethery) Date: 2009-08-24 22:29
No problem. I can parse text in an automated manner very easily. So if  
you need someone to take the doc files and add in wiki URLs for each  
section, I can do that. Happy to volunteer. Worst case is you look at  
what I do and reject it. Best case ... I actually do what you need.
Thanks, Kee

On Aug 24, 2009, at 10:26 AM, Georg Brandl wrote:

>
> Georg Brandl <georg@python.org> added the comment:
>
> At the moment, I still have to review and merge the SoC branch, so  
> don't
> expect visible changes to happen within a few weeks.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue6660>
> _______________________________________

-------------------------------------------------
I check email roughly 2 to 3 times per business day.
Kagi main office: +1 (510) 550-1336
History
Date User Action Args
2009-08-24 22:29:38keenetherysetmessages: + msg91944
2009-08-24 17:26:19georg.brandlsetmessages: + msg91931
2009-08-11 15:17:04keenetherysetmessages: + msg91476
2009-08-07 15:53:31keenetherysetmessages: + msg91406
2009-08-06 22:38:31georg.brandlsetmessages: + msg91390
2009-08-06 21:56:16keenetherysetmessages: + msg91389
2009-08-06 17:56:42georg.brandlsetstatus: open -> closed
resolution: later
messages: + msg91375
2009-08-06 17:49:43keenetherycreate