On 08/12/2009 01:58 AM, Steven D'Aprano wrote: > On Tue, 11 Aug 2009 14:50:51 -0700, rurpy wrote: > >>>> The issue tracker is fine for many things, but the process it provides >>>> is equivalent to peep-hole optimization. How does one submit a >>>> tracker issue for something like the overall organization of the docs >>>> (for example, the mis-placement of things like data- types in the >>>> library manual rather than the language manual)? >>> The same way you would submit a tracker issue for anything. >>> >>> "Documentation bug: Data types are misplaced in the library manual >>> instead of the language manual. >>> >>> Suggested alternative: move page docs.python.org/xyz.html to abc.html" >> But that's the problem. Such a reorg is not a simple matter of moving a >> file from here to there. It will require a lot moving about of sections >> and a lot of word-smithing to glue them back together again in a >> coherent way. > > That's no different from *any* major refactoring. The exact same problem > exists for code as well as documentation. It's a solved problem for code, > and it's a solved problem for documentation.
Huh? I don't buy this at all. Code refactoring doesn't change the semantics of the program at all -- it simplifies the code that implements behavior without changing behavior. How does this apply to revising documentation? It may be true that some of the same techniques applicable to maintaining code are applicable to documentation but I need a lot more than your assertion to believe they are as equivalent as you seem to be claiming. > In some order: > > Consensus that there is a problem that needs solving; > Volunteer(s) to do the work; > Somebody to take responsibility to check the changes in. That's not refactoring as I understand it -- that is making a large change. I don't see that that addresses the problem of getting a large patch approved or the other issues I mentioned. > Sometimes, in the face of apathy or disagreement (which may very well be > justified), you have to at least partly solve the problem *before* people > will agree that it needed to be solved. Welcome to the real world. > >> A tracker issue, even one that was fairly specific about how things >> should be reorganized but which did not provide all the needed changes >> (a large patch) would almost certainly be ignored or rejected. > > Yes it would. Most patches are ignored, because the dev team are > overworked, and if they don't see the need for a patch, they won't > approve it. I'm confused. If they weren't overworked, then they would approve patches they didn't see a need for? Or are you saying because they are overworked they fail to approve patches that should be approved? I am not sure how either supports the argument that the tracker is the best method of improving the docs. >> But >> providing a large patch raises two questions. How likely is it to be be >> accepted? (Something anyone would want to know before investing the >> time.) And how to actually do the work needed to generate it (it could >> be a very large amount of work for an individual and I don't think it >> can be broken down into small independent issues.) How is one to test >> the waters as to acceptability, or solicit help, if one simply submits a >> tracker issue? > > No, submitting a tracker issue is a necessary but not sufficient step. > Without a tracker issue, you're very unlikely to have people agree to > replace the existing docs with your docs, although a PEP would probably > do it. (A PEP is significantly more effort than raising a tracker issue.) Has there ever been a PEP for a doc change? Are you making a serious suggestion? > You also have to get attention from those with check-in privileges. If > they approve your patches, you're done. If they don't approve them, or > fail to respond, you can try convincing them, or taking it to the Python- > Dev list and request somebody review your patches. > > If you have no patches, perhaps because you're unwilling to invest the > effort without a guarantee that it will be treated seriously, then you > need to get some sort of consensus among the relevant people that the > problem is worth solving. You are again describing the current process, not the issue of whether the current process is the optimal one or not. And while I would never expect a guarantee that a particular submission would be accepted, I think I would need, if not a guarantee, at least a high expectation that a submission would be treated seriously before I invested a large amount of work in it. > Guess what? Sometimes others will disagree with you. What you see as the > Worst. Docs. EVAR. may be seen as perfectly adequate, even excellent, by > others. If this is the case, remember, Python isn't your product, you > don't have veto over what goes into it. Feel free to publish your > alternatives. Write a book. Go home and cry into your beer over it. > Whatever. Sometimes you win, and sometimes you don't. Right, this is obvious. But the other side of that coin is that if people who see problems with the docs perceive that those who control access to the docs have no interest in changing them, then the first group will likely post their complaints on this newsgroup. If you don't like that then you have the same choices you listed above. Of course if the docs really are that good, there will relatively few complaints and the vast majority of readers will recognize the few complaints as invalid and ignore them, so if you are right that the docs are good enough, there should be no problem. > This is the same process whether dealing with code or documentation. > >>> - if people are keen on a Python wiki, then by all means publish one, >>> just don't expect the Python dev team to build and manage it for you; >> As luminous a Pythoneer as Fredrik Lundh set up a documentation wiki to >> collect user contributions but it has faded away. If he couldn't pull >> it off then I'd say most other attempts without the backing of >> python.org are almost certainly doomed to failure. > > Perhaps that's a good indication that a Python wiki *doesn't* fulfill a > need in the community, and that despite what a few squeaky wheels think, > the docs *are* doing a good job? That fails to explain the repeated criticisms of the docs here and in blogs. Of course this argument is not likely to convince you since there is no reliable quantitative support for the claim that there are more complaints about the docs than other aspects of Python -- it relies on each individual's powers of observation. But you also have to explain away very specific criticisms of the docs such as Xah Lee's as invalid or exceptions. >> As long as every "the docs >> sux" complaint is met here with the standard responses that I've >> mentioned, > > But they aren't met with such a so-called "standard response". I just looked through the first 70 or so messages in this thread and in this case I have agree with you, most of the responses were not what I called "standard responses". There was one guy, a Steven D'Aprano early on that trotted out the, "it's free software, fix it if you don't like it" line, and the troll epithet was used a time or two, but the vast majority were in fact reasonable and thoughtful responses. I will try to find some examples from other past threads. >> rather than, "yes, they do have some problems, what do you >> think we should do about them?", > > We know that there are problems. We've said repeatedly that corrections > and patches are welcome. We've repeatedly told you how to communicate > your answer to the question of what should be done. None of this is good > enough for you. I don't know what else you expect. You have been told repeatedly why your insistence that the tracker must be the only channel, is wrong. I don't understand why you can't understand that. (Generally only those in authority, bosses, parents, police, and the like, "tell" others what a situation is and have a right to demand that the subject accept it without question. I think you could find a more respectful and less authoritarian way of phrasing what you said above since you are not in a position of authority over me.) And who exactly is this "we" that you are a member of? >>> If you won't put in the effort, and you won't put in the money, then it >>> won't happen. Moaning that other people aren't putting in the money to >>> hire team of professional writers isn't productive, and moaning that >>> other people aren't putting in the effort to improve the docs isn't >>> either. >> Eh? I have a computer filled with software that I put no money or >> effort into, yet there it is. > > Ah yes, I'm sorry, I missed one other alternative: sit around and wait > for somebody else to put in the money and/or effort. > >> That some of us choose to >> invest it somewhere other than Python does not deprive of of our right >> to point out problems in Python when we note them. > > Of course not. But it does mean that you won't be taken seriously, and > you have no right to be taken seriously. On usenet no one has a right to anything. You can take my posts however you wish. I've tried to make reasonable arguments to support my view (with the understanding that these are usenet posts, not a doctoral thesis). But you (and the unnamed "we" above) seem to feel that public complaints or discussion about better alternatives to the current doc improvement process are somehow out-of-bounds. I'm sorry, I disagree. -- http://mail.python.org/mailman/listinfo/python-list
