| 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) *  |
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) * |
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: [] 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) * |
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 |
|
|