On Wed, Sep 22, 2010 at 10:38 PM, Brett Cannon <brett@python.org> wrote:
the first thing on the agenda is a complete rewrite of the developer docs and moving them into the Doc/ directory
I'd like to know why you think moving the developer docs into the CPython tree makes sense. My own thought here is that they're not specific to the version of Python, though some of the documentation deals with the group of specific branches being maintained. For me, keeping them in a separate space (like www.python.org/dev/) makes sense. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> "A storm broke loose in my mind." --Albert Einstein
A discussion occurred (w/o me) on #python-dev where moving it to Doc/ would allow it to show up at docs.python.org to perhaps get more people involved. It also allows developers to contribute to the docs w/o having to get pydotorg commit rights. On Wed, Sep 22, 2010 at 21:29, Fred Drake <fdrake@acm.org> wrote:
That's right. It is true that it isn't branch-specific information, and that does cause a little bit of irritation for me too, but neither is Misc/developers.txt or Misc/maintainers.rst. Of course, we might consider a separate HG repository (I'm all in favor of many small repos, instead of a gigantic sandbox one). The downside is that I really like the developer docs at docs.python.org, and it would complicate the build process a bit. Georg Am 23.09.2010 06:45, schrieb Brett Cannon:
-- 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.
On Thu, Sep 23, 2010 at 2:40 AM, Georg Brandl <g.brandl@gmx.net> wrote:
Agreed. I'd rather those were elsewhere as well, but I was paying less attention at the time.
Perhaps someone here knows enough about our documentation toolchain to figure out a way to generate a link from the docs to developer docs on the website. :-) I expect only a very small part of the audience for the general Python documentation & CPython docs are particularly interested in the development process we use, and sending them to the website from a convenient link is not a bad thing. We won't even need a new repository to do that. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> "A storm broke loose in my mind." --Albert Einstein
On Sep 23, 2010, at 08:40 AM, Georg Brandl wrote:
Ideally, I would really like to see the developer docs live outside the CPython source repository. There's no reason to tie the dev docs to CPython's svn merge policies, write acls, or release schedules. Given the way docs.python.org is stitched together, and the fact that we (still ;) haven't moved to a dvcs, this may not be feasible. These docs are better off in the wiki than in the source tree. -Barry
On Sep 23, 2010, at 09:06 AM, Benjamin Peterson wrote:
Are any of our docs subject to release schedules?
I guess what I'm concerned about is this scenario: You're a developer who has the source code to Python 3.1. You read the in-tree docs to get a sense of how our development process works. Now, you're a diligent and eager new contributor so you follow those instructions to the letter. Unfortunately, Python 3.5 is the current version and we've changed key parts of the process. There's no possible way that your 3.1 in-tree docs can be updated to reflect the new process. Okay, we can tell you to get the Python 3.5 code, or probably better yet, the Python 3.6 in-development trunk, but now we've got another dilemma. If we change the process in 3.6, there will be pressure to update the docs in 3.5 and previous versions that are still officially maintained. And what about security-only versions of Python? Our development processes are *primarily* independent of Python version, so I don't think they should be tied to our source tree, and our CPython source tree at that. I suspect the version-dependent instructions will be minimal and can be handled by the rare footnotes or whatever. IMHO of course, -Barry
On Thu, 23 Sep 2010 10:41:35 -0400, Barry Warsaw <barry@python.org> wrote:
Except for major changes like the transition to hg, the dev process is no more likely to change than the code base (probably less!). That is, the eager developers with the 3.1 source code are just as likely to produce a patch that won't be useful because it doesn't apply to the current maintained versions as they are to encounter a piece of the dev process that has changed enough to break what they tried to do. (In this context, the switch to hg is analogous to the switch to Python3...) Also, the existence of the docs in the repository is (IMO) for *editing* convenience. The real place a new developer will be looking at the docs is on the web site, just as the place most people (even developers, unless I miss my guess; I know I do) look for Python documentation is on the web site. And that version will be up to date.
Yes, and? We update the docs of the maintained Python versions all the time. Doc backports are standard (even if Georg does most of them in batches) unless the documentation is about a new feature. The fact that even 'new features' of the dev process would also get backported is merely a detail. We don't update docs for security releases as far as I know, so I would expect we wouldn't update the dev docs either.
I don't think our development process applies to anything other than the CPython source. (At least at the moment...if we break out the stdlib that will change, but at that point the stdlib should have its own distinct development process, even if that process shares most of its features with the CPython one.) Our documentation is *primarily* independent of Python version, too, if you go by the ratio of the word count of the substantive changes from version to version to the word count of the docs as a whole :) True, the dev docs are even more independent, but I don't see that as trumping the convenience to the developers of having them in the source tree. A separate repository would also be fine, IMO. If someone can find or write the code to publish that repository to the appropriate location automatically, we could presumably do this even before the rest of the hg transition. --David
On Sep 23, 2010, at 11:49 AM, R. David Murray wrote:
I'm not necessarily opposed to that either. I do think the switch to hg will cause lots of churn in the dev process, ultimately for the better, but there will be experiment and change at least for the code contribution bits. I'm also not as worried about the authority of the wiki. If we get good contributors and the rest of the community starts linking to wiki urls, it will feel (more) official. Anyway, it's all kind of secondary to actually writing stuff down. <wink> If Brett's going to do the work, then he gets to decide. :) -Barry
On Thu, Sep 23, 2010 at 09:05, Barry Warsaw <barry@python.org> wrote:
Whether it is in Doc/ or a separate Hg repo, I don't care. But I am not doing it in the wiki. While I am totally fine with wikis as a general community thing where community input and editing is good, this is not one of those cases. Our development process belongs to python-dev and thus should be influenced by its members. I do not want to have to police the dev docs after I write them because someone either disagreed or misunderstood what was expected. For something this formal and official I want pro-active instead of reactive editorial oversight.
Am 23.09.2010 16:41, schrieb Barry Warsaw:
That's a pity, of course; however the small amount of bug reports we get that reflects content in old (= unsupported) library documentation suggests that it would not be a problem in practice: Most people look at docs.python.org anyway.
Well, with Mercurial we're supposed to check in all changes to the oldest branch they apply to. If everyone changing the dev docs keeps to that, all supported versions will have up-to-date docs. 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.
On Sep 23, 2010, at 10:43 AM, Jesse Noller wrote:
Bummer. There's no reason it *has* to be useless though. The Moin developer now has shell access, so if there are technical problems with wiki, like its theme, performance, or lack of features, we can get those fixed. If it's the content or organization that needs improvement, then we can recruit from the much larger Python community than those that have write access to the core svn. Let's honor and encourage folks who are really good at tending to wikis and give them the tools they need to make the wiki excellent. Of course, if the consensus is that wikis are just a waste of time and do more harm than good, then we should shut ours down. (I don't agree it is though.) -Barry
On Thu, Sep 23, 2010 at 10:53 AM, Barry Warsaw <barry@python.org> wrote:
To be honest; while I have a strong dislike for them - I think they work fine for unofficial sources of information, I don't think they work well for official "we stand by this" style information. So, no, I don't think it's totally useless, but I do think it's an information sinkhole, and I would never seriously publish anything I had to stand by to a "completely public" wiki personally. The larger community, however, probably finds it useful to have it as a resource, even as scattered and spottily curated as it can be - I just don't think it's a good location for official developer/development docs. I don't think we have the needed curation resources to keep on top of the willy-nilly editing wikis incur. jesse
On Thu, 23 Sep 2010 10:53:55 -0400 Barry Warsaw <barry@python.org> wrote:
Of course, if the consensus is that wikis are just a waste of time and do more harm than good, then we should shut ours down. (I don't agree it is though.)
I don't think they are a waste of time. However, as you and Dirkjan pointed out, a wiki needs some "gardening" to take care of its structure and its presentation. The present Python wiki isn't very inviting graphically, and its structure doesn't look very thought out. Regards Antoine.
On Sep 23, 2010, at 05:32 PM, Antoine Pitrou wrote:
I certainly agree with that. So, how can we solve those problems? Radomir has shell access now so perhaps we can ask him to make the Python wiki theme more visually appealing. What roadblocks do people encounter when they want to help garden or reorganize the wiki? -Barry
On Thu, 23 Sep 2010 11:57:19 -0400 Barry Warsaw <barry@python.org> wrote:
Given that few or none of us seem to (want to) actively contribute to the wiki, I'm afraid python-dev is not the place to ask. Perhaps a call should be issued on c.l.py asking interested people to subscribe to pydotorg (or any other list) and start there? By the way, I've just looked at the wiki: there are 2 or 3 edits per day. Compared to the size and vitality of the Python user community, this is a ridiculously low number. Regards Antoine.
Antoine> Given that few or none of us seem to (want to) actively Antoine> contribute to the wiki, I'm afraid python-dev is not the place Antoine> to ask. Perhaps a call should be issued on c.l.py ... It would be nice if you could actually send messages to the people who do actually update wiki content. Unfortunately, without donning my cape and blue tights, then digging into the users files on the wiki there's no real way to do that. Skip
On Fri, Sep 24, 2010 at 4:52 AM, <skip@pobox.com> wrote:
That's a good point actually... why *isn't* there a pydotorg-wiki-sig? (Aside from the obvious point of nobody ever asking for one). I must admit, that the various things I've thrown on there myself have been pretty much fire-and-forget. Without anyone that feels like they collectively "own" the wiki, the much needed pruning never happens. With an admin team behind it, you can also make more use of ACLs to flag certain parts of the wiki as "official" by making them only editable by certain people (e.g. only devs, only the triage team, only the wiki admins). But keeping those user lists up to date is itself something that requires a strong wiki admin team. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Am 24.09.2010 00:39, schrieb Guido van Rossum:
I don't actually know entirely; at a minimum, Skip Montanaro.
IIUC, this is primarily for spam protection, though.
So would they object against additions to the team?
I don't think they would. Regards, Martin
On 24/09/2010 06:46, "Martin v. Löwis" wrote:
Wiki maintenance is discussed, along with other python.org maintenance topics, on the pydotorg-www mailing list: http://mail.python.org/mailman/listinfo/pydotorg-www More wiki and website maintainers needed! All the best, Michael Foord
-- http://www.ironpythoninaction.com/ http://www.voidspace.org.uk/blog READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.
On Fri, Sep 24, 2010 at 8:31 PM, Michael Foord <fuzzyman@voidspace.org.uk> wrote:
We could probably advertise helping with pydotorg itself a bit more in the "How can I help?" sections of the docs and website. I did just notice there is actually a "Help Maintain Website" on the left of the main page which is a good start, but (for example) the general Python FAQ in the docs points people to http://python.org/dev/, which in turn has a "Suggested Tasks" link to http://python.org/dev/contributing/. That page could probably do with a section in the main text that links to the website maintenance info page. That page itself could also mention assisting in wiki maintenance as a way to demonstrate interest (similar to the way patches and triage assistance show interest in contributing to the official docs and source code). For the wiki itself, I would suggest a "Help Maintain the Wiki" link in the left navbar of each (with appropriately updated text, that could just link to the general website maintenance page). So, given that we don't actually *ask* anywhere for people to contribute to the wiki, I guess it isn't that surprising that it is underutilised. Something else the wiki can be *very* useful for is to provide information that is potentially useful to Python users, but that we don't want to be seen as unduly "blessed" by either python-dev or the PSF. Lists of libraries supporting particular tasks can fit into that category, since an entry on an open access wiki page is (justifiably) going to be given far less weight than a reference from the official documentation. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Fri, Sep 24, 2010 at 3:31 AM, Michael Foord <fuzzyman@voidspace.org.uk> wrote:
Which has hidden its membership (even to members). Does it really need to appear that secretive? At least the message archive is open and has all the usual suspects.
More wiki and website maintainers needed!
Maybe a prominent wiki page with info about how to join the list and the responsibilities / needs would help? Also, I gotta say that the wiki login process is awkward. -- --Guido van Rossum (python.org/~guido)
On Fri, Sep 24, 2010 at 1:31 PM, Michael Foord <fuzzyman@voidspace.org.uk> wrote:
More wiki and website maintainers needed!
That's the consequence. You need to seek the reason why there are no maintainers or active members on pydotorg-www lists. I've expressed my thoughts earlier. On Fri, Sep 24, 2010 at 6:40 AM, Steven D'Aprano <steve@pearwood.info> wrote:
For me, the number one roadblock is unfamiliarity -- I always forget that there is a Python wiki.
For me a major annoyance is the empty page with two links on wiki.python.org While it allows to tell new people that there is also a Jython wiki, my vision that it should be instead be oriented on existing contributors immediately providing instruments to work with Python wiki. So if smb. need Jython wiki - it should be moved to wiki.jython.org I'd start from there. Who can do this? -- anatoly t.
On Sat, Sep 25, 2010 at 8:22 AM, anatoly techtonik <techtonik@gmail.com> wrote:
That's funny, I've never seen that page before. Does it get linked to from somewhere? -- David blog: http://www.traceback.org twitter: http://twitter.com/dstanek
Am 25.09.2010 15:15, schrieb David Stanek:
It's at <http://wiki.python.org/>, and FTR, it has annoyed me as well. 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.
Am 25.09.2010 23:43, schrieb "Martin v. Löwis":
Redirect wiki.python.org to the Python wiki front page, and put the Jython wiki somewhere on its own (whether it's wiki.jython.org or not). The only people who will need a pointer are those who went directly to wiki.python.org/ and intended to go to the Jython wiki; a link might be added on the front page of the Python wiki. 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.
Am 26.09.2010 00:16, schrieb "Martin v. Löwis":
Why -- they can be redirected easily. 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.
On Sun, Sep 26, 2010 at 2:18 AM, "Martin v. Löwis" <martin@v.loewis.de> wrote:
* Shorten URLs - remove /moin/ prefix from http://wiki.python.org/moin/SiteImprovements#Wiki * This requires moving Jython wiki from http://wiki.python.org/jython/ to http://wiki.jython.org/ and placing a temporary redirect on the previous places. -- ?techtonik 2010-03-16 08:39:34 Expanding: 1. Move http://wiki.python.org/moin/ to http://wiki.python.org/ 2. Setup 301 redirect from http://wiki.python.org/moin/(.*) to http://wiki.python.org/$1 3. Setup 301 redirect from http://wiki.python.org/jython/(.*) to http://wiki.jython.org/$1 (optional tasks below) 4. Setup Analytics account to track sources of redirection to the old pages and make this list public 5. Crowdsource changing source links 6. Drop redirection after redirected hits drop below 5% (even for 5% new page can be looked up through Google) -- anatoly t.
On Sun, Sep 26, 2010 at 8:16 AM, "Martin v. Löwis" <martin@v.loewis.de> wrote:
But that can't work: then off-site links into either wiki break.
Georg isn't suggesting a general structural change, just a change to have the URL when you land *directly* on wiki.python.org automatically rewritten to resolve to wiki.python.org/moin. Any URL with additional path info would be handled the same as it is now. I've certainly run into this, since Firefox will turn "wiki.p" into wiki.python.org for me and it (mildly) irritates me every time that that doesn't actually take me to the front page of the wiki. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Sun, Sep 26, 2010 at 10:59 PM, "Martin v. Löwis" <martin@v.loewis.de> wrote:
I don't actually have any specific preference as to implementation details, aside from it being something that works without breaking the rest of the web server :) Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Am 26.09.2010 14:59, schrieb "Martin v. Löwis":
I've been talking about redirecting all the time, haven't I? Plan is simple: * redirect from wiki.python.org to wiki.python.org/moin * (optionally) redirect from wiki.jython.org to wiki.python.org/jython -- or -- make wiki.jython.org the canonical URI for the Jython wiki and redirect from old /jython URIs there. 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.
On 9/26/2010 10:25 AM, "Martin v. Löwis" wrote:
Strikes me this is a much needed change. Thanks! regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 DjangoCon US September 7-9, 2010 http://djangocon.us/ See Python Video! http://python.mirocommunity.org/ Holden Web LLC http://www.holdenweb.com/
On Sun, Sep 26, 2010 at 03:53:58PM +0200, Georg Brandl wrote:
* redirect from wiki.python.org to wiki.python.org/moin
I've added a <meta http-equiv> element to the top page of wiki.python.org, so browsers will now jump to the /moin/ page immediately. This won't help crawlers that don't parse the HTML, but that probably doesn't matter. --amk
On Fri, Sep 24, 2010 at 1:27 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:
That's bad. I'd really like to see the amount of my contributions so far. How about recording a session on MoinMoin hacking and drafting an upgrade plan? Who's gonna be the driver?
That's a good point actually... why *isn't* there a pydotorg-wiki-sig? (Aside from the obvious point of nobody ever asking for one).
Because Yet Another Mailing List doesn't solve the problem. If you need one - go Google Groups like packaging folks did. Python ML are: 1. require dedicated admin to update, who is not a member of the group 2. don't have search 3. don't have optional thread subscription That's already enough to seek better platform for collaboration.
Community can perfectly manage the stuff without dedicated admins if there is a gameplay in it. I am doing the wiki works when I am redirected to outdated wiki pages from search. But I do it only if it doesn't take me more than 5 minutes, and if I can remember the password (and I know where an edit button is). My advice - subscribe people editing page by default (a checkbox near submit button). This way more people will receive notifications when a page is changed and will be more interested to contribute themselves. Of course, there must be a setting to opt out.
That's a dead way. Wiki should be open for everyone. Just need more people subscribed to revert unwelcome changes. That is to make timeline more visible, because on wiki.python.org it is _not_ intuitive. It may worth to see how Mercurial wiki is managed - I've picked up the bookmarks monitoring habit from it. Maybe a design change will help, but again - there is no entrypoint for people with design skills to start. A lot of problems. All on the surface. Mailing list won't help. What's next? -- anatoly t.
On Sat, Sep 25, 2010 at 6:20 PM, anatoly techtonik <techtonik@gmail.com> wrote:
My experience with the auto-nosy setting on Roundup actually makes me quite positive towards this idea. It's especially useful when coupled with the query for "Issues followed by me" and the new "add me to the nosy list" button. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Hello Le 25/09/2010 10:20, anatoly techtonik a écrit :
Re: thread subscription, there is a setting about topics in the mailman admin but I don’t understand it. I suppose a good email client can do something equivalent.
collaborative area to hash things out, before they can become official code or docs.
Regards
On Sep 27, 2010, at 10:36 PM, Éric Araujo wrote:
ObPlug: You can always read the archives at Gmane (e.g. via web or nntp) or mail-archive.com, both of which are searchable. Or you can help improve the world of open source mail archivers by getting involved in the Mailman project and helping us build the next generation archiver. :) -Barry
Éric Araujo writes:
Le 25/09/2010 10:20, anatoly techtonik a écrit :
Indeed. Mailman doesn't require a dedicated admin to operate, only to set up. Some things go better if you've got part-time admins (moderation in particular). I agree with techtonik that a better platform is apparently needed, but this is a client-server system, and the problem is in the client. Ie, he should upgrade his MUA to one that does threading properly, and allows priorities to be given to threads. (Emacs/Gnus is the one I'm familiar with but surely there are others.) This is a contextual judgment, not an absolute: apparently most Python devs *do* use sufficiently powerful MUAs for their purposes. It makes sense for the minority to adopt the majority practice.
Re: thread subscription, there is a setting about topics in the mailman admin but I don’t understand it.
Mailman topics are a clumsy Subject-based filter, and require admin intervention to set up. They're quite valuable for low-to-medium- traffic lists with a variety of more or less defined topics (ie, if there were more traffic, you'd want to split the list), but are pretty much useless for this purpose.
No, they're not just trusted people. They're trusted people with greater privilege than the rest of us, and therefore a bottleneck for some operations.
My advice - subscribe people editing page by default (a checkbox near submit button).
+1 wholeheartedly.
That default needs to be user-configurable. I would not want to be spammed with typo corrections on a page where all I did was correct a typo. I probably wouldn't even want to see major changes by default: I came, I saw, I conquered the typo and got my info, now leave me alone!
I don't think we want to change the image of the wiki (as in "anybody can edit")! What we may want is (1) to make it easy for those with the authority to update the official docs (but there's a very good story for putting them in a repo, perhaps associated with the sources, so this is a weak argument for reference-docs-in-wiki), and (2) make it easy for readers to cross reference the community documentation (often more detailed or less intimidatingly formal) and the reference manuals. (1) *may* suggest using the wiki engine to support editing, but I think most devs are strongly against that. (2) suggests using the wiki engine to easily or even automatically set up cross-references. I think that wiki is probably the best technology for this purpose at the present time, but I don't know if it's worth the effort to make the official documentation wiki-friendly (in the sense of allowing the wiki to generate links to community documentation from the reference manuals).
On Thu, Sep 23, 2010 at 6:57 PM, Barry Warsaw <barry@python.org> wrote:
First of all Wiki is outdated. Correct me, but python.org specific customizations are not modules, but patches that makes it hard to update the Wiki to latest version or add new customizations. Second - ugly Creole syntax. I am for inter-cooperation between wikis, and I understand that for non-developer communities [] symbols imposing problems, but as an open source developer I am addicted to Trac and Google Code syntax and never had problems with those. Third - there is not starting point to help with wiki. No instructions how to checkout wiki code, how to get python.org modification, how to get sample data and how to get started. This place should be easily editable by anyone (premoderated for disrespectful members), so anyone can share their experience. Take a look at Trac. Fourth. GPL license. I personally don't have interest to waste my time for the code I won't be able to use in some projects, unless the project is either exceptional (Mercurial) or interesting. To make python.org MoinMoin interesting - there should be an inviting entrypoint (see point three above) and the list of tasks to choose form. Something that is better than http://wiki.python.org/moin/SiteImprovements Fifth. Credits and motivation for all python.org works. I still convinced that there should be one primary dedicated list and it should be public. All sensitive issues can be discussed with webmasters@ privately, but the primary list should be run by community. Not the volunteers who are better than others. If there will be a feeling that site is run by community, then you can expect contributions. Otherwise expect the community to think "they're doing the stuff here, so they will fix it". -- anatoly t.
Am 23.09.2010 22:25, schrieb anatoly techtonik:
That's why we have a Moin core developer on the team. ISTM that Moin 1.x is notoriously hard to extend -- once you go beyond plugins adding new wiki macros -- which is part of what the team wants to fix in 2.x.
This isn't Creole syntax, it's Moin wiki syntax. And face it, it's not going to change. It's also not so much different from Trac wiki syntax.
Yes, that needs to be updated indeed.
I'm puzzled what you expect in addition to the pydotorg-www list. 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.
On Fri, 24 Sep 2010 01:57:19 am Barry Warsaw wrote:
For me, the number one roadblock is unfamiliarity -- I always forget that there is a Python wiki. I think it would be helpful if the wiki could be integrated with the docs in some fashion, perhaps by having each page link to a sister page in the wiki. It seems to me that the wiki won't be useful until people regularly use it, and people won't regularly use it until it is useful. It will take a conscious effort by people (including myself) to break this vicious circle by improving articles and regularly linking to them. Number two, I just went to the wiki to see how I might get started. I randomly choose this page: http://wiki.python.org/moin/BeginnersGuide/Download and looked for an edit button or something. Unlike Wikipedia, there is no obvious Edit button. Eventually I noticed in tiny type at the bottom of the page: "Immutable page". Hmmm, that's not promising. Then I discovered a *tiny* icon that looks like a speech bubble that apparently means "edit". Clicking it gives me a message: "You are not allowed to edit this page." Not friendly, nor helpful. A better message might be something like "This page is locked. You must log in to edit this page." or similar. How does one get an account? Can I edit anonymously? Once I found a page I could edit, it was relatively straightforward. So that's a plus :) -- Steven D'Aprano
Antoine> The present Python wiki isn't very inviting graphically, and Antoine> its structure doesn't look very thought out. I imagine it can be made to look more like the rest of python.org without a lot of trouble. As to the structure, like most wikis it quickly resembles a bag-o-pages after awhile. Thank goodness for Google. Skip
I don't think there is (or can be) consensus about that. However, Jesse's objection is fairly widespread also, and it is not specific for wiki.python.org, or MoinMoin, but opposing Wikis as general. By nature (quick-quick), information is unorganized in a Wiki. This is what wiki advocates cite as its main feature, and wiki opponents as its main flaw. Regards, Martin
On Fri, 24 Sep 2010 01:42:03 am Martin v. Löwis wrote:
I've never heard wiki advocates say that, and even a cursory glace at wikis like Wikipedia disprove the idea that wikis are necessarily disorganised. "Quick" does not mean unstructured, disorganised or unorganised. Do you mean that the *contributors* to the wiki are disorganised, rather than the wiki itself? If so, perhaps, but again Wikipedia demonstrates that this is not necessarily the case. Wikipedia has a hierarchy of contributors. In reverse order: - anonymous editors - editors with accounts - administrators - Wikimedia Foundation, which is responsible for policy - BDFL Jimmy Wales who is ultimately responsible for setting policy One of the criticisms of Wikipedia is that it has diverged from its official aim to be the encyclopedia that anyone can edit to one where contributions from insiders, particularly "the Cabal", are preferred to those of new anonymous editors. Other wikis have other policies: Citizendium and Scholarpedia are notable examples that attempt to increase the (real or perceived) reliability and accountability of their articles by prohibiting anonymous edits altogether. Despite the influence of Wikipedia, "wiki" does not mean "open to everyone to edit without supervision". -- Steven D'Aprano
On Thu, Sep 23, 2010 at 7:35 AM, Barry Warsaw <barry@python.org> wrote:
I have to agree with Jesse. We have too many wiki pages that are so out of date they're dangerous. They serve a purpose, and I think we should have a wiki in addition to the "official" documentation. This could be aggressively linked from it so people can comment on that documentation -- a commenting system like the PHP docs have would be even better, but that's been an unimplemented idea for so long that I'm not holding my hopes up. But when one person (or a small group) sits down to write the "official" guidelines for doing something, I think using proper revision control and so on can only help improve the docs and keep them up to date. -- --Guido van Rossum (python.org/~guido)
You must have forgotten that you lent the time machine keys to Georg, though :-) http://gsoc.jacobmason.us/blog/?p=35 http://bitbucket.org/jacobmason/sphinx-web-support http://gsoc.jacobmason.us/demo/contents Regards, Martin
On Thu, Sep 23, 2010 at 8:52 AM, "Martin v. Löwis" <martin@v.loewis.de> wrote:
But before Georg returns the keys, he should make sure to install this on docs.python.org. :-) (I like it, but it needs some work. The login page needs instructions for people who've forgotten how to use OpenID. There needs to be an introduction on how to use the comment system at the root of the site. It would be nice to allow anonymous comments (with a way for site managers to turn this off on a per-page basis). And it would be nice if there was a pop-up with snippets of comments when you mouse over a comment bubble.) -- --Guido van Rossum (python.org/~guido)
Am 23.09.2010 16:47, schrieb Guido van Rossum:
You should read my tweets more often :) Yes, I know I promised this for last year, but this time the code is already merged, and I "just" need to polish and set it up on docs.python.org. 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.
Am 23.09.2010 16:35, schrieb Barry Warsaw:
Don't worry, as soon as my thesis is gone for good, I will have time to finally make good use of the new features in Sphinx trunk, among them the often request commenting and patching feature. The result -- I dare say -- will be the best of both worlds: no unsupervised changes in content, but the possibility of instant feedback for readers. We'll require some more people wrangling the amount of information we get, but I've got quite a few requests from the community asking for things to help the docs; now I have to refer them to the tracker, which can be less than satisfying, then I can recruit them into the comment-handling team. 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.
On Thu, 23 Sep 2010 00:29:51 -0400 Fred Drake <fdrake@acm.org> wrote:
Many parts of the library docs aren't version-specific either :) The dev docs may differ slightly from one version to another, for example if a version introduces some new possibilities for tooling, or far-reaching implementation changes (think Unladen Swallow). The practicality argument of being able to edit those docs without having to master a separate (pydotorg) workflow sounds quite strong to me. Regards Antoine.
On 23/09/2010 11:11, Antoine Pitrou wrote:
+1 Michael
-- http://www.ironpythoninaction.com/ http://www.voidspace.org.uk/blog READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.
On Thu, Sep 23, 2010 at 6:11 AM, Antoine Pitrou <solipsis@pitrou.net> wrote:
Agreed with Antoine here the additional workflow/repo/build process/etc sucks Besides - who cares if only a subset of users would be interested in our workflow? If it's more than 0, and it helps bring on new contributors, who cares? If we can make it easier to maintain information, and find that information, why not do it? jesse
On Thu, Sep 23, 2010 at 8:11 PM, Antoine Pitrou <solipsis@pitrou.net> wrote:
This is the key point for me. For developer controlled stuff, the easiest place to have it if we want it kept up to date is in the source tree. Second best is the wiki. Having it off in a separately managed repository (that exists for perfectly valid reasons, since a lot of the content *isn't* developer controlled) is annoying. That said, in this case, what's the advantage of the source tree over the wiki? To include it in the main docs, so people reading them offline can still see the contribution workflow? Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Thu, 23 Sep 2010 23:35:02 +1000, Nick Coghlan <ncoghlan@gmail.com> wrote:
I'd *much* rather edit rst files than futz with a web interface when editing docs. The wiki also somehow feels "less official". I do think exposing our development process to the wider user community by including them in the main docs could foster additional community involvement, but I don't have a strong opinion on that aspect of it. For me the change is about making it easier for the dev community (who are using/creating the development infrastructure) to update the relevant documentation. -- R. David Murray www.bitdance.com
On 23/09/2010 15:16, R. David Murray wrote:
+1 Keeping the dev docs in the development tree sounds good to me (however they are deployed to the web - but preferably automagically). Michael
-- http://www.ironpythoninaction.com/ http://www.voidspace.org.uk/blog READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.
On Thu, 23 Sep 2010 10:16:01 -0400 "R. David Murray" <rdmurray@bitdance.com> wrote:
I agree with the "less official" point. If our developer docs feel authoritative, people will be more encouraged to contribute. Also, the wiki in its current state looks much less polished than the Sphinx-generated docs. Regards Antoine.
On Sep 23, 2010, at 10:16 AM, R. David Murray wrote:
I'd *much* rather edit rst files than futz with a web interface when editing docs. The wiki also somehow feels "less official".
There are dvcs-backed wikis, for example: https://launchpad.net/wikkid :) I don't agree that the wiki feels less official, or perhaps that it *should* feel any less official. It's an important source of Pythonic information, and to me it feels much more inclusive and open. -Barry
Am 23.09.2010 16:33, schrieb Barry Warsaw:
This impression comes along with the authority of potential authors. If only the release manager can write a document, it is very official. If any committer can write, but nobody else, it feels less officical. If anybody could modify the document, it's even less official. Since anybody can write to the Python wiki, it feels not very official. It's the same reason why people often trust Wikipedia less than a printed encyclopedia. Regards, Martin
On Thu, Sep 23, 2010 at 7:47 AM, "Martin v. Löwis" <martin@v.loewis.de> wrote:
I want to believe your theory (since I also have a feeling that some wiki pages feel less trustworthy than others) but my own use of Wikipedia makes me skeptical that this is all there is -- on many pages on important topics you can clearly tell that a lot of effort went into the article, and then I trust it more. On other places you can tell that almost nobody cared. But I never look at the names of the authors. -- --Guido van Rossum (python.org/~guido)
On Thu, Sep 23, 2010 at 16:56, Guido van Rossum <guido@python.org> wrote:
Right -- I feel like wiki quality varies with the amount of attention spent on maintaining it. Wikis that get a lot of maintenance (or have someone devoted to "wiki gardening") will be good (consistent and up to date), while wikis that are only occasionally updated, or updated without much consistency or added to without editing get to feel bad. Seems like a variation of the broken window theory. So what we really need is a way to make editing the developer docs more rewarding (or less hard) for potential authors (i.e. python committers). If putting it in a proper VCS so they can use their editor of choice would help that, that seems like a good solution. Cheers, Dirkjan
Hello All, I am new to this list, but I have been lurking around getting a feel for the environment and processes. I had some discussion yesterday about the developer documentation as well, since it’s what I do professionally. I am a technical writer but also work in the web development arena (using Django). In fact one of my projects now is to develop a comprehensive platform for distributing online help, user documentation, etc. which I am just about to put up on BitBucket (winter ’10). Anyway, that said, with regard to Wikis. I have worked in several organizations where almost all of the development documentation was maintained on a wiki. This can be great for getting up and running with something quickly, but over time it becomes very unmanageable and confusing. What I have done in various organizations has been to create a system where an official repository is kept with all of the *official* documentation and a way for users (developers) to submit their proposals as to what they would like to add and change. These proposals are kept in a tracker where they are read and evaluated. Generally, some discussion ensues and the choices are made as to what stays published or changed. This is what the system I am writing is all about as well. It maintains the documentation, and allows for users to comment on various parts of that documentation and submit requests to change or add. The admins can then change or deny the documentation based on community response. Anyway, I am not pitching my idea or trying to hump my system but I will be releasing it before winter on BitBucket for anyone to try and distribute freely. I do however, discourage the use of wikis at all costs. It has been said that they feel loose and unofficial, and although that my not be the intent, over time this becomes reality. Anyway, thank you for your time. Warmest Regards, Steve On Thu, Sep 23, 2010 at 11:06 AM, Dirkjan Ochtman <dirkjan@ochtman.nl>wrote:
On Fri, 24 Sep 2010 01:50:34 am Steven Elliott Jr wrote:
Surely that depends on how widely you give write-privileges to the wiki? If you wouldn't give arbitrary people write-access to your documentation repository, why would you give them write-access to your wiki? If the wiki doesn't allow you control who has read and write access, then use a different wiki. I'm not familiar with any wiki that doesn't allow you to track and review history of the documents. Some of them are just web interfaces to standard VCSes like Mercurial. Wikipedia is now experimenting with "pending changes" and having stable and unstable versions of pages. I've known people to work themselves into a tizz at the thought of their developers making "unauthorized" changes to the documentation, while not even tracking changes to the source code *at all*, let alone reviewing the commits. This makes no sense to me at all -- if you (generic you, not you specifically) trust your developers to make changes to the source code, why not trust them to make changes to the documentation? The real problem, it seems to me, is the difficulty in getting developers to write and update documentation, not in preventing them from writing it. -- Steven D'Aprano
On Thu, 23 Sep 2010 07:56:19 -0700, Guido van Rossum <guido@python.org> wrote:
I think you've hit the nail on the head. The Python wiki pages mostly feel like nobody cares. At least that's the case for the ones I've stumbled across. And I'd include my own contributions in that (the email-sig wiki), because I was using them as a work area and have not updated them in some time, since development is now in a code repository. If we can recruit a bunch of somebodies who *do* care, then the wiki would be much more useful. But I still don't want to edit the dev docs there, if I have a choice :) There's a reason I stopped updating the wiki as soon as I moved to a code repository. -- R. David Murray www.bitdance.com
If we can recruit a bunch of somebodies who *do* care, then the wiki
I think that there are plenty that do care; I for one would be more than happy to work on whatever documentation needs might arise for this group. I am a bit of a documentation nut, since its what I do, also I come from the Django camp where people are obsessive over documentation. I still think that wikis are not the best solution but if that is something that needs to be tightened up then it would be something that I personally would have no problem working on.
A discussion occurred (w/o me) on #python-dev where moving it to Doc/ would allow it to show up at docs.python.org to perhaps get more people involved. It also allows developers to contribute to the docs w/o having to get pydotorg commit rights. On Wed, Sep 22, 2010 at 21:29, Fred Drake <fdrake@acm.org> wrote:
That's right. It is true that it isn't branch-specific information, and that does cause a little bit of irritation for me too, but neither is Misc/developers.txt or Misc/maintainers.rst. Of course, we might consider a separate HG repository (I'm all in favor of many small repos, instead of a gigantic sandbox one). The downside is that I really like the developer docs at docs.python.org, and it would complicate the build process a bit. Georg Am 23.09.2010 06:45, schrieb Brett Cannon:
-- 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.
On Thu, Sep 23, 2010 at 2:40 AM, Georg Brandl <g.brandl@gmx.net> wrote:
Agreed. I'd rather those were elsewhere as well, but I was paying less attention at the time.
Perhaps someone here knows enough about our documentation toolchain to figure out a way to generate a link from the docs to developer docs on the website. :-) I expect only a very small part of the audience for the general Python documentation & CPython docs are particularly interested in the development process we use, and sending them to the website from a convenient link is not a bad thing. We won't even need a new repository to do that. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> "A storm broke loose in my mind." --Albert Einstein
On Sep 23, 2010, at 08:40 AM, Georg Brandl wrote:
Ideally, I would really like to see the developer docs live outside the CPython source repository. There's no reason to tie the dev docs to CPython's svn merge policies, write acls, or release schedules. Given the way docs.python.org is stitched together, and the fact that we (still ;) haven't moved to a dvcs, this may not be feasible. These docs are better off in the wiki than in the source tree. -Barry
On Sep 23, 2010, at 09:06 AM, Benjamin Peterson wrote:
Are any of our docs subject to release schedules?
I guess what I'm concerned about is this scenario: You're a developer who has the source code to Python 3.1. You read the in-tree docs to get a sense of how our development process works. Now, you're a diligent and eager new contributor so you follow those instructions to the letter. Unfortunately, Python 3.5 is the current version and we've changed key parts of the process. There's no possible way that your 3.1 in-tree docs can be updated to reflect the new process. Okay, we can tell you to get the Python 3.5 code, or probably better yet, the Python 3.6 in-development trunk, but now we've got another dilemma. If we change the process in 3.6, there will be pressure to update the docs in 3.5 and previous versions that are still officially maintained. And what about security-only versions of Python? Our development processes are *primarily* independent of Python version, so I don't think they should be tied to our source tree, and our CPython source tree at that. I suspect the version-dependent instructions will be minimal and can be handled by the rare footnotes or whatever. IMHO of course, -Barry
On Thu, 23 Sep 2010 10:41:35 -0400, Barry Warsaw <barry@python.org> wrote:
Except for major changes like the transition to hg, the dev process is no more likely to change than the code base (probably less!). That is, the eager developers with the 3.1 source code are just as likely to produce a patch that won't be useful because it doesn't apply to the current maintained versions as they are to encounter a piece of the dev process that has changed enough to break what they tried to do. (In this context, the switch to hg is analogous to the switch to Python3...) Also, the existence of the docs in the repository is (IMO) for *editing* convenience. The real place a new developer will be looking at the docs is on the web site, just as the place most people (even developers, unless I miss my guess; I know I do) look for Python documentation is on the web site. And that version will be up to date.
Yes, and? We update the docs of the maintained Python versions all the time. Doc backports are standard (even if Georg does most of them in batches) unless the documentation is about a new feature. The fact that even 'new features' of the dev process would also get backported is merely a detail. We don't update docs for security releases as far as I know, so I would expect we wouldn't update the dev docs either.
I don't think our development process applies to anything other than the CPython source. (At least at the moment...if we break out the stdlib that will change, but at that point the stdlib should have its own distinct development process, even if that process shares most of its features with the CPython one.) Our documentation is *primarily* independent of Python version, too, if you go by the ratio of the word count of the substantive changes from version to version to the word count of the docs as a whole :) True, the dev docs are even more independent, but I don't see that as trumping the convenience to the developers of having them in the source tree. A separate repository would also be fine, IMO. If someone can find or write the code to publish that repository to the appropriate location automatically, we could presumably do this even before the rest of the hg transition. --David
On Sep 23, 2010, at 11:49 AM, R. David Murray wrote:
I'm not necessarily opposed to that either. I do think the switch to hg will cause lots of churn in the dev process, ultimately for the better, but there will be experiment and change at least for the code contribution bits. I'm also not as worried about the authority of the wiki. If we get good contributors and the rest of the community starts linking to wiki urls, it will feel (more) official. Anyway, it's all kind of secondary to actually writing stuff down. <wink> If Brett's going to do the work, then he gets to decide. :) -Barry
On Thu, Sep 23, 2010 at 09:05, Barry Warsaw <barry@python.org> wrote:
Whether it is in Doc/ or a separate Hg repo, I don't care. But I am not doing it in the wiki. While I am totally fine with wikis as a general community thing where community input and editing is good, this is not one of those cases. Our development process belongs to python-dev and thus should be influenced by its members. I do not want to have to police the dev docs after I write them because someone either disagreed or misunderstood what was expected. For something this formal and official I want pro-active instead of reactive editorial oversight.
Am 23.09.2010 16:41, schrieb Barry Warsaw:
That's a pity, of course; however the small amount of bug reports we get that reflects content in old (= unsupported) library documentation suggests that it would not be a problem in practice: Most people look at docs.python.org anyway.
Well, with Mercurial we're supposed to check in all changes to the oldest branch they apply to. If everyone changing the dev docs keeps to that, all supported versions will have up-to-date docs. 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.
On Sep 23, 2010, at 10:43 AM, Jesse Noller wrote:
Bummer. There's no reason it *has* to be useless though. The Moin developer now has shell access, so if there are technical problems with wiki, like its theme, performance, or lack of features, we can get those fixed. If it's the content or organization that needs improvement, then we can recruit from the much larger Python community than those that have write access to the core svn. Let's honor and encourage folks who are really good at tending to wikis and give them the tools they need to make the wiki excellent. Of course, if the consensus is that wikis are just a waste of time and do more harm than good, then we should shut ours down. (I don't agree it is though.) -Barry
On Thu, Sep 23, 2010 at 10:53 AM, Barry Warsaw <barry@python.org> wrote:
To be honest; while I have a strong dislike for them - I think they work fine for unofficial sources of information, I don't think they work well for official "we stand by this" style information. So, no, I don't think it's totally useless, but I do think it's an information sinkhole, and I would never seriously publish anything I had to stand by to a "completely public" wiki personally. The larger community, however, probably finds it useful to have it as a resource, even as scattered and spottily curated as it can be - I just don't think it's a good location for official developer/development docs. I don't think we have the needed curation resources to keep on top of the willy-nilly editing wikis incur. jesse
On Thu, 23 Sep 2010 10:53:55 -0400 Barry Warsaw <barry@python.org> wrote:
Of course, if the consensus is that wikis are just a waste of time and do more harm than good, then we should shut ours down. (I don't agree it is though.)
I don't think they are a waste of time. However, as you and Dirkjan pointed out, a wiki needs some "gardening" to take care of its structure and its presentation. The present Python wiki isn't very inviting graphically, and its structure doesn't look very thought out. Regards Antoine.
On Sep 23, 2010, at 05:32 PM, Antoine Pitrou wrote:
I certainly agree with that. So, how can we solve those problems? Radomir has shell access now so perhaps we can ask him to make the Python wiki theme more visually appealing. What roadblocks do people encounter when they want to help garden or reorganize the wiki? -Barry
On Thu, 23 Sep 2010 11:57:19 -0400 Barry Warsaw <barry@python.org> wrote:
Given that few or none of us seem to (want to) actively contribute to the wiki, I'm afraid python-dev is not the place to ask. Perhaps a call should be issued on c.l.py asking interested people to subscribe to pydotorg (or any other list) and start there? By the way, I've just looked at the wiki: there are 2 or 3 edits per day. Compared to the size and vitality of the Python user community, this is a ridiculously low number. Regards Antoine.
Antoine> Given that few or none of us seem to (want to) actively Antoine> contribute to the wiki, I'm afraid python-dev is not the place Antoine> to ask. Perhaps a call should be issued on c.l.py ... It would be nice if you could actually send messages to the people who do actually update wiki content. Unfortunately, without donning my cape and blue tights, then digging into the users files on the wiki there's no real way to do that. Skip
On Fri, Sep 24, 2010 at 4:52 AM, <skip@pobox.com> wrote:
That's a good point actually... why *isn't* there a pydotorg-wiki-sig? (Aside from the obvious point of nobody ever asking for one). I must admit, that the various things I've thrown on there myself have been pretty much fire-and-forget. Without anyone that feels like they collectively "own" the wiki, the much needed pruning never happens. With an admin team behind it, you can also make more use of ACLs to flag certain parts of the wiki as "official" by making them only editable by certain people (e.g. only devs, only the triage team, only the wiki admins). But keeping those user lists up to date is itself something that requires a strong wiki admin team. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Am 24.09.2010 00:39, schrieb Guido van Rossum:
I don't actually know entirely; at a minimum, Skip Montanaro.
IIUC, this is primarily for spam protection, though.
So would they object against additions to the team?
I don't think they would. Regards, Martin
On 24/09/2010 06:46, "Martin v. Löwis" wrote:
Wiki maintenance is discussed, along with other python.org maintenance topics, on the pydotorg-www mailing list: http://mail.python.org/mailman/listinfo/pydotorg-www More wiki and website maintainers needed! All the best, Michael Foord
-- http://www.ironpythoninaction.com/ http://www.voidspace.org.uk/blog READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.
On Fri, Sep 24, 2010 at 8:31 PM, Michael Foord <fuzzyman@voidspace.org.uk> wrote:
We could probably advertise helping with pydotorg itself a bit more in the "How can I help?" sections of the docs and website. I did just notice there is actually a "Help Maintain Website" on the left of the main page which is a good start, but (for example) the general Python FAQ in the docs points people to http://python.org/dev/, which in turn has a "Suggested Tasks" link to http://python.org/dev/contributing/. That page could probably do with a section in the main text that links to the website maintenance info page. That page itself could also mention assisting in wiki maintenance as a way to demonstrate interest (similar to the way patches and triage assistance show interest in contributing to the official docs and source code). For the wiki itself, I would suggest a "Help Maintain the Wiki" link in the left navbar of each (with appropriately updated text, that could just link to the general website maintenance page). So, given that we don't actually *ask* anywhere for people to contribute to the wiki, I guess it isn't that surprising that it is underutilised. Something else the wiki can be *very* useful for is to provide information that is potentially useful to Python users, but that we don't want to be seen as unduly "blessed" by either python-dev or the PSF. Lists of libraries supporting particular tasks can fit into that category, since an entry on an open access wiki page is (justifiably) going to be given far less weight than a reference from the official documentation. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Fri, Sep 24, 2010 at 3:31 AM, Michael Foord <fuzzyman@voidspace.org.uk> wrote:
Which has hidden its membership (even to members). Does it really need to appear that secretive? At least the message archive is open and has all the usual suspects.
More wiki and website maintainers needed!
Maybe a prominent wiki page with info about how to join the list and the responsibilities / needs would help? Also, I gotta say that the wiki login process is awkward. -- --Guido van Rossum (python.org/~guido)
On Fri, Sep 24, 2010 at 1:31 PM, Michael Foord <fuzzyman@voidspace.org.uk> wrote:
More wiki and website maintainers needed!
That's the consequence. You need to seek the reason why there are no maintainers or active members on pydotorg-www lists. I've expressed my thoughts earlier. On Fri, Sep 24, 2010 at 6:40 AM, Steven D'Aprano <steve@pearwood.info> wrote:
For me, the number one roadblock is unfamiliarity -- I always forget that there is a Python wiki.
For me a major annoyance is the empty page with two links on wiki.python.org While it allows to tell new people that there is also a Jython wiki, my vision that it should be instead be oriented on existing contributors immediately providing instruments to work with Python wiki. So if smb. need Jython wiki - it should be moved to wiki.jython.org I'd start from there. Who can do this? -- anatoly t.
On Sat, Sep 25, 2010 at 8:22 AM, anatoly techtonik <techtonik@gmail.com> wrote:
That's funny, I've never seen that page before. Does it get linked to from somewhere? -- David blog: http://www.traceback.org twitter: http://twitter.com/dstanek
Am 25.09.2010 15:15, schrieb David Stanek:
It's at <http://wiki.python.org/>, and FTR, it has annoyed me as well. 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.
Am 25.09.2010 23:43, schrieb "Martin v. Löwis":
Redirect wiki.python.org to the Python wiki front page, and put the Jython wiki somewhere on its own (whether it's wiki.jython.org or not). The only people who will need a pointer are those who went directly to wiki.python.org/ and intended to go to the Jython wiki; a link might be added on the front page of the Python wiki. 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.
Am 26.09.2010 00:16, schrieb "Martin v. Löwis":
Why -- they can be redirected easily. 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.
On Sun, Sep 26, 2010 at 2:18 AM, "Martin v. Löwis" <martin@v.loewis.de> wrote:
* Shorten URLs - remove /moin/ prefix from http://wiki.python.org/moin/SiteImprovements#Wiki * This requires moving Jython wiki from http://wiki.python.org/jython/ to http://wiki.jython.org/ and placing a temporary redirect on the previous places. -- ?techtonik 2010-03-16 08:39:34 Expanding: 1. Move http://wiki.python.org/moin/ to http://wiki.python.org/ 2. Setup 301 redirect from http://wiki.python.org/moin/(.*) to http://wiki.python.org/$1 3. Setup 301 redirect from http://wiki.python.org/jython/(.*) to http://wiki.jython.org/$1 (optional tasks below) 4. Setup Analytics account to track sources of redirection to the old pages and make this list public 5. Crowdsource changing source links 6. Drop redirection after redirected hits drop below 5% (even for 5% new page can be looked up through Google) -- anatoly t.
On Sun, Sep 26, 2010 at 8:16 AM, "Martin v. Löwis" <martin@v.loewis.de> wrote:
But that can't work: then off-site links into either wiki break.
Georg isn't suggesting a general structural change, just a change to have the URL when you land *directly* on wiki.python.org automatically rewritten to resolve to wiki.python.org/moin. Any URL with additional path info would be handled the same as it is now. I've certainly run into this, since Firefox will turn "wiki.p" into wiki.python.org for me and it (mildly) irritates me every time that that doesn't actually take me to the front page of the wiki. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Sun, Sep 26, 2010 at 10:59 PM, "Martin v. Löwis" <martin@v.loewis.de> wrote:
I don't actually have any specific preference as to implementation details, aside from it being something that works without breaking the rest of the web server :) Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Am 26.09.2010 14:59, schrieb "Martin v. Löwis":
I've been talking about redirecting all the time, haven't I? Plan is simple: * redirect from wiki.python.org to wiki.python.org/moin * (optionally) redirect from wiki.jython.org to wiki.python.org/jython -- or -- make wiki.jython.org the canonical URI for the Jython wiki and redirect from old /jython URIs there. 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.
On 9/26/2010 10:25 AM, "Martin v. Löwis" wrote:
Strikes me this is a much needed change. Thanks! regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 DjangoCon US September 7-9, 2010 http://djangocon.us/ See Python Video! http://python.mirocommunity.org/ Holden Web LLC http://www.holdenweb.com/
On Sun, Sep 26, 2010 at 03:53:58PM +0200, Georg Brandl wrote:
* redirect from wiki.python.org to wiki.python.org/moin
I've added a <meta http-equiv> element to the top page of wiki.python.org, so browsers will now jump to the /moin/ page immediately. This won't help crawlers that don't parse the HTML, but that probably doesn't matter. --amk
On Fri, Sep 24, 2010 at 1:27 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:
That's bad. I'd really like to see the amount of my contributions so far. How about recording a session on MoinMoin hacking and drafting an upgrade plan? Who's gonna be the driver?
That's a good point actually... why *isn't* there a pydotorg-wiki-sig? (Aside from the obvious point of nobody ever asking for one).
Because Yet Another Mailing List doesn't solve the problem. If you need one - go Google Groups like packaging folks did. Python ML are: 1. require dedicated admin to update, who is not a member of the group 2. don't have search 3. don't have optional thread subscription That's already enough to seek better platform for collaboration.
Community can perfectly manage the stuff without dedicated admins if there is a gameplay in it. I am doing the wiki works when I am redirected to outdated wiki pages from search. But I do it only if it doesn't take me more than 5 minutes, and if I can remember the password (and I know where an edit button is). My advice - subscribe people editing page by default (a checkbox near submit button). This way more people will receive notifications when a page is changed and will be more interested to contribute themselves. Of course, there must be a setting to opt out.
That's a dead way. Wiki should be open for everyone. Just need more people subscribed to revert unwelcome changes. That is to make timeline more visible, because on wiki.python.org it is _not_ intuitive. It may worth to see how Mercurial wiki is managed - I've picked up the bookmarks monitoring habit from it. Maybe a design change will help, but again - there is no entrypoint for people with design skills to start. A lot of problems. All on the surface. Mailing list won't help. What's next? -- anatoly t.
On Sat, Sep 25, 2010 at 6:20 PM, anatoly techtonik <techtonik@gmail.com> wrote:
My experience with the auto-nosy setting on Roundup actually makes me quite positive towards this idea. It's especially useful when coupled with the query for "Issues followed by me" and the new "add me to the nosy list" button. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Hello Le 25/09/2010 10:20, anatoly techtonik a écrit :
Re: thread subscription, there is a setting about topics in the mailman admin but I don’t understand it. I suppose a good email client can do something equivalent.
collaborative area to hash things out, before they can become official code or docs.
Regards
On Sep 27, 2010, at 10:36 PM, Éric Araujo wrote:
ObPlug: You can always read the archives at Gmane (e.g. via web or nntp) or mail-archive.com, both of which are searchable. Or you can help improve the world of open source mail archivers by getting involved in the Mailman project and helping us build the next generation archiver. :) -Barry
Éric Araujo writes:
Le 25/09/2010 10:20, anatoly techtonik a écrit :
Indeed. Mailman doesn't require a dedicated admin to operate, only to set up. Some things go better if you've got part-time admins (moderation in particular). I agree with techtonik that a better platform is apparently needed, but this is a client-server system, and the problem is in the client. Ie, he should upgrade his MUA to one that does threading properly, and allows priorities to be given to threads. (Emacs/Gnus is the one I'm familiar with but surely there are others.) This is a contextual judgment, not an absolute: apparently most Python devs *do* use sufficiently powerful MUAs for their purposes. It makes sense for the minority to adopt the majority practice.
Re: thread subscription, there is a setting about topics in the mailman admin but I don’t understand it.
Mailman topics are a clumsy Subject-based filter, and require admin intervention to set up. They're quite valuable for low-to-medium- traffic lists with a variety of more or less defined topics (ie, if there were more traffic, you'd want to split the list), but are pretty much useless for this purpose.
No, they're not just trusted people. They're trusted people with greater privilege than the rest of us, and therefore a bottleneck for some operations.
My advice - subscribe people editing page by default (a checkbox near submit button).
+1 wholeheartedly.
That default needs to be user-configurable. I would not want to be spammed with typo corrections on a page where all I did was correct a typo. I probably wouldn't even want to see major changes by default: I came, I saw, I conquered the typo and got my info, now leave me alone!
I don't think we want to change the image of the wiki (as in "anybody can edit")! What we may want is (1) to make it easy for those with the authority to update the official docs (but there's a very good story for putting them in a repo, perhaps associated with the sources, so this is a weak argument for reference-docs-in-wiki), and (2) make it easy for readers to cross reference the community documentation (often more detailed or less intimidatingly formal) and the reference manuals. (1) *may* suggest using the wiki engine to support editing, but I think most devs are strongly against that. (2) suggests using the wiki engine to easily or even automatically set up cross-references. I think that wiki is probably the best technology for this purpose at the present time, but I don't know if it's worth the effort to make the official documentation wiki-friendly (in the sense of allowing the wiki to generate links to community documentation from the reference manuals).
On Thu, Sep 23, 2010 at 6:57 PM, Barry Warsaw <barry@python.org> wrote:
First of all Wiki is outdated. Correct me, but python.org specific customizations are not modules, but patches that makes it hard to update the Wiki to latest version or add new customizations. Second - ugly Creole syntax. I am for inter-cooperation between wikis, and I understand that for non-developer communities [] symbols imposing problems, but as an open source developer I am addicted to Trac and Google Code syntax and never had problems with those. Third - there is not starting point to help with wiki. No instructions how to checkout wiki code, how to get python.org modification, how to get sample data and how to get started. This place should be easily editable by anyone (premoderated for disrespectful members), so anyone can share their experience. Take a look at Trac. Fourth. GPL license. I personally don't have interest to waste my time for the code I won't be able to use in some projects, unless the project is either exceptional (Mercurial) or interesting. To make python.org MoinMoin interesting - there should be an inviting entrypoint (see point three above) and the list of tasks to choose form. Something that is better than http://wiki.python.org/moin/SiteImprovements Fifth. Credits and motivation for all python.org works. I still convinced that there should be one primary dedicated list and it should be public. All sensitive issues can be discussed with webmasters@ privately, but the primary list should be run by community. Not the volunteers who are better than others. If there will be a feeling that site is run by community, then you can expect contributions. Otherwise expect the community to think "they're doing the stuff here, so they will fix it". -- anatoly t.
Am 23.09.2010 22:25, schrieb anatoly techtonik:
That's why we have a Moin core developer on the team. ISTM that Moin 1.x is notoriously hard to extend -- once you go beyond plugins adding new wiki macros -- which is part of what the team wants to fix in 2.x.
This isn't Creole syntax, it's Moin wiki syntax. And face it, it's not going to change. It's also not so much different from Trac wiki syntax.
Yes, that needs to be updated indeed.
I'm puzzled what you expect in addition to the pydotorg-www list. 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.
On Fri, 24 Sep 2010 01:57:19 am Barry Warsaw wrote:
For me, the number one roadblock is unfamiliarity -- I always forget that there is a Python wiki. I think it would be helpful if the wiki could be integrated with the docs in some fashion, perhaps by having each page link to a sister page in the wiki. It seems to me that the wiki won't be useful until people regularly use it, and people won't regularly use it until it is useful. It will take a conscious effort by people (including myself) to break this vicious circle by improving articles and regularly linking to them. Number two, I just went to the wiki to see how I might get started. I randomly choose this page: http://wiki.python.org/moin/BeginnersGuide/Download and looked for an edit button or something. Unlike Wikipedia, there is no obvious Edit button. Eventually I noticed in tiny type at the bottom of the page: "Immutable page". Hmmm, that's not promising. Then I discovered a *tiny* icon that looks like a speech bubble that apparently means "edit". Clicking it gives me a message: "You are not allowed to edit this page." Not friendly, nor helpful. A better message might be something like "This page is locked. You must log in to edit this page." or similar. How does one get an account? Can I edit anonymously? Once I found a page I could edit, it was relatively straightforward. So that's a plus :) -- Steven D'Aprano
Antoine> The present Python wiki isn't very inviting graphically, and Antoine> its structure doesn't look very thought out. I imagine it can be made to look more like the rest of python.org without a lot of trouble. As to the structure, like most wikis it quickly resembles a bag-o-pages after awhile. Thank goodness for Google. Skip
I don't think there is (or can be) consensus about that. However, Jesse's objection is fairly widespread also, and it is not specific for wiki.python.org, or MoinMoin, but opposing Wikis as general. By nature (quick-quick), information is unorganized in a Wiki. This is what wiki advocates cite as its main feature, and wiki opponents as its main flaw. Regards, Martin
On Fri, 24 Sep 2010 01:42:03 am Martin v. Löwis wrote:
I've never heard wiki advocates say that, and even a cursory glace at wikis like Wikipedia disprove the idea that wikis are necessarily disorganised. "Quick" does not mean unstructured, disorganised or unorganised. Do you mean that the *contributors* to the wiki are disorganised, rather than the wiki itself? If so, perhaps, but again Wikipedia demonstrates that this is not necessarily the case. Wikipedia has a hierarchy of contributors. In reverse order: - anonymous editors - editors with accounts - administrators - Wikimedia Foundation, which is responsible for policy - BDFL Jimmy Wales who is ultimately responsible for setting policy One of the criticisms of Wikipedia is that it has diverged from its official aim to be the encyclopedia that anyone can edit to one where contributions from insiders, particularly "the Cabal", are preferred to those of new anonymous editors. Other wikis have other policies: Citizendium and Scholarpedia are notable examples that attempt to increase the (real or perceived) reliability and accountability of their articles by prohibiting anonymous edits altogether. Despite the influence of Wikipedia, "wiki" does not mean "open to everyone to edit without supervision". -- Steven D'Aprano
On Thu, Sep 23, 2010 at 7:35 AM, Barry Warsaw <barry@python.org> wrote:
I have to agree with Jesse. We have too many wiki pages that are so out of date they're dangerous. They serve a purpose, and I think we should have a wiki in addition to the "official" documentation. This could be aggressively linked from it so people can comment on that documentation -- a commenting system like the PHP docs have would be even better, but that's been an unimplemented idea for so long that I'm not holding my hopes up. But when one person (or a small group) sits down to write the "official" guidelines for doing something, I think using proper revision control and so on can only help improve the docs and keep them up to date. -- --Guido van Rossum (python.org/~guido)
You must have forgotten that you lent the time machine keys to Georg, though :-) http://gsoc.jacobmason.us/blog/?p=35 http://bitbucket.org/jacobmason/sphinx-web-support http://gsoc.jacobmason.us/demo/contents Regards, Martin
On Thu, Sep 23, 2010 at 8:52 AM, "Martin v. Löwis" <martin@v.loewis.de> wrote:
But before Georg returns the keys, he should make sure to install this on docs.python.org. :-) (I like it, but it needs some work. The login page needs instructions for people who've forgotten how to use OpenID. There needs to be an introduction on how to use the comment system at the root of the site. It would be nice to allow anonymous comments (with a way for site managers to turn this off on a per-page basis). And it would be nice if there was a pop-up with snippets of comments when you mouse over a comment bubble.) -- --Guido van Rossum (python.org/~guido)
Am 23.09.2010 16:47, schrieb Guido van Rossum:
You should read my tweets more often :) Yes, I know I promised this for last year, but this time the code is already merged, and I "just" need to polish and set it up on docs.python.org. 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.
Am 23.09.2010 16:35, schrieb Barry Warsaw:
Don't worry, as soon as my thesis is gone for good, I will have time to finally make good use of the new features in Sphinx trunk, among them the often request commenting and patching feature. The result -- I dare say -- will be the best of both worlds: no unsupervised changes in content, but the possibility of instant feedback for readers. We'll require some more people wrangling the amount of information we get, but I've got quite a few requests from the community asking for things to help the docs; now I have to refer them to the tracker, which can be less than satisfying, then I can recruit them into the comment-handling team. 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.
On Thu, 23 Sep 2010 00:29:51 -0400 Fred Drake <fdrake@acm.org> wrote:
Many parts of the library docs aren't version-specific either :) The dev docs may differ slightly from one version to another, for example if a version introduces some new possibilities for tooling, or far-reaching implementation changes (think Unladen Swallow). The practicality argument of being able to edit those docs without having to master a separate (pydotorg) workflow sounds quite strong to me. Regards Antoine.
On 23/09/2010 11:11, Antoine Pitrou wrote:
+1 Michael
-- http://www.ironpythoninaction.com/ http://www.voidspace.org.uk/blog READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.
On Thu, Sep 23, 2010 at 6:11 AM, Antoine Pitrou <solipsis@pitrou.net> wrote:
Agreed with Antoine here the additional workflow/repo/build process/etc sucks Besides - who cares if only a subset of users would be interested in our workflow? If it's more than 0, and it helps bring on new contributors, who cares? If we can make it easier to maintain information, and find that information, why not do it? jesse
On Thu, Sep 23, 2010 at 8:11 PM, Antoine Pitrou <solipsis@pitrou.net> wrote:
This is the key point for me. For developer controlled stuff, the easiest place to have it if we want it kept up to date is in the source tree. Second best is the wiki. Having it off in a separately managed repository (that exists for perfectly valid reasons, since a lot of the content *isn't* developer controlled) is annoying. That said, in this case, what's the advantage of the source tree over the wiki? To include it in the main docs, so people reading them offline can still see the contribution workflow? Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Thu, 23 Sep 2010 23:35:02 +1000, Nick Coghlan <ncoghlan@gmail.com> wrote:
I'd *much* rather edit rst files than futz with a web interface when editing docs. The wiki also somehow feels "less official". I do think exposing our development process to the wider user community by including them in the main docs could foster additional community involvement, but I don't have a strong opinion on that aspect of it. For me the change is about making it easier for the dev community (who are using/creating the development infrastructure) to update the relevant documentation. -- R. David Murray www.bitdance.com
On 23/09/2010 15:16, R. David Murray wrote:
+1 Keeping the dev docs in the development tree sounds good to me (however they are deployed to the web - but preferably automagically). Michael
-- http://www.ironpythoninaction.com/ http://www.voidspace.org.uk/blog READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.
On Thu, 23 Sep 2010 10:16:01 -0400 "R. David Murray" <rdmurray@bitdance.com> wrote:
I agree with the "less official" point. If our developer docs feel authoritative, people will be more encouraged to contribute. Also, the wiki in its current state looks much less polished than the Sphinx-generated docs. Regards Antoine.
On Sep 23, 2010, at 10:16 AM, R. David Murray wrote:
I'd *much* rather edit rst files than futz with a web interface when editing docs. The wiki also somehow feels "less official".
There are dvcs-backed wikis, for example: https://launchpad.net/wikkid :) I don't agree that the wiki feels less official, or perhaps that it *should* feel any less official. It's an important source of Pythonic information, and to me it feels much more inclusive and open. -Barry
Am 23.09.2010 16:33, schrieb Barry Warsaw:
This impression comes along with the authority of potential authors. If only the release manager can write a document, it is very official. If any committer can write, but nobody else, it feels less officical. If anybody could modify the document, it's even less official. Since anybody can write to the Python wiki, it feels not very official. It's the same reason why people often trust Wikipedia less than a printed encyclopedia. Regards, Martin
On Thu, Sep 23, 2010 at 7:47 AM, "Martin v. Löwis" <martin@v.loewis.de> wrote:
I want to believe your theory (since I also have a feeling that some wiki pages feel less trustworthy than others) but my own use of Wikipedia makes me skeptical that this is all there is -- on many pages on important topics you can clearly tell that a lot of effort went into the article, and then I trust it more. On other places you can tell that almost nobody cared. But I never look at the names of the authors. -- --Guido van Rossum (python.org/~guido)
On Thu, Sep 23, 2010 at 16:56, Guido van Rossum <guido@python.org> wrote:
Right -- I feel like wiki quality varies with the amount of attention spent on maintaining it. Wikis that get a lot of maintenance (or have someone devoted to "wiki gardening") will be good (consistent and up to date), while wikis that are only occasionally updated, or updated without much consistency or added to without editing get to feel bad. Seems like a variation of the broken window theory. So what we really need is a way to make editing the developer docs more rewarding (or less hard) for potential authors (i.e. python committers). If putting it in a proper VCS so they can use their editor of choice would help that, that seems like a good solution. Cheers, Dirkjan
Hello All, I am new to this list, but I have been lurking around getting a feel for the environment and processes. I had some discussion yesterday about the developer documentation as well, since it’s what I do professionally. I am a technical writer but also work in the web development arena (using Django). In fact one of my projects now is to develop a comprehensive platform for distributing online help, user documentation, etc. which I am just about to put up on BitBucket (winter ’10). Anyway, that said, with regard to Wikis. I have worked in several organizations where almost all of the development documentation was maintained on a wiki. This can be great for getting up and running with something quickly, but over time it becomes very unmanageable and confusing. What I have done in various organizations has been to create a system where an official repository is kept with all of the *official* documentation and a way for users (developers) to submit their proposals as to what they would like to add and change. These proposals are kept in a tracker where they are read and evaluated. Generally, some discussion ensues and the choices are made as to what stays published or changed. This is what the system I am writing is all about as well. It maintains the documentation, and allows for users to comment on various parts of that documentation and submit requests to change or add. The admins can then change or deny the documentation based on community response. Anyway, I am not pitching my idea or trying to hump my system but I will be releasing it before winter on BitBucket for anyone to try and distribute freely. I do however, discourage the use of wikis at all costs. It has been said that they feel loose and unofficial, and although that my not be the intent, over time this becomes reality. Anyway, thank you for your time. Warmest Regards, Steve On Thu, Sep 23, 2010 at 11:06 AM, Dirkjan Ochtman <dirkjan@ochtman.nl>wrote:
On Fri, 24 Sep 2010 01:50:34 am Steven Elliott Jr wrote:
Surely that depends on how widely you give write-privileges to the wiki? If you wouldn't give arbitrary people write-access to your documentation repository, why would you give them write-access to your wiki? If the wiki doesn't allow you control who has read and write access, then use a different wiki. I'm not familiar with any wiki that doesn't allow you to track and review history of the documents. Some of them are just web interfaces to standard VCSes like Mercurial. Wikipedia is now experimenting with "pending changes" and having stable and unstable versions of pages. I've known people to work themselves into a tizz at the thought of their developers making "unauthorized" changes to the documentation, while not even tracking changes to the source code *at all*, let alone reviewing the commits. This makes no sense to me at all -- if you (generic you, not you specifically) trust your developers to make changes to the source code, why not trust them to make changes to the documentation? The real problem, it seems to me, is the difficulty in getting developers to write and update documentation, not in preventing them from writing it. -- Steven D'Aprano
On Thu, 23 Sep 2010 07:56:19 -0700, Guido van Rossum <guido@python.org> wrote:
I think you've hit the nail on the head. The Python wiki pages mostly feel like nobody cares. At least that's the case for the ones I've stumbled across. And I'd include my own contributions in that (the email-sig wiki), because I was using them as a work area and have not updated them in some time, since development is now in a code repository. If we can recruit a bunch of somebodies who *do* care, then the wiki would be much more useful. But I still don't want to edit the dev docs there, if I have a choice :) There's a reason I stopped updating the wiki as soon as I moved to a code repository. -- R. David Murray www.bitdance.com
If we can recruit a bunch of somebodies who *do* care, then the wiki
I think that there are plenty that do care; I for one would be more than happy to work on whatever documentation needs might arise for this group. I am a bit of a documentation nut, since its what I do, also I come from the Django camp where people are obsessive over documentation. I still think that wikis are not the best solution but if that is something that needs to be tightened up then it would be something that I personally would have no problem working on.
participants (23)
-
"Martin v. Löwis" -
A.M. Kuchling -
anatoly techtonik -
Antoine Pitrou -
Barry Warsaw -
Benjamin Peterson -
Brett Cannon -
David Stanek -
Dirkjan Ochtman -
Fred Drake -
Georg Brandl -
Glenn Linderman -
Guido van Rossum -
Jesse Noller -
Michael Foord -
Nick Coghlan -
R. David Murray -
skip＠pobox.com -
Stephen J. Turnbull -
Steve Holden -
Steven D'Aprano -
Steven Elliott Jr -
Éric Araujo