On Sun, Jul 4, 2010 at 2:05 PM, dffdgsdfgsdfhjhtre <nbvf...@gmail.com>wrote:
> There are two types of documentation, "reference" documentation > (articles explaining all about one specific object such as slugify or > the Feed class), and "topical" documentation (articles explaining how > to do stuff like write templates). > > It seems right now, django's documentation is trying to do both at the > same time. > I agree that sometimes django's documentation can be a mixture of those two kinds, but I think it is not a problem that appears throughout all the docs, but in some rare places. > One project that does reference documentation really well, > imo, is PHP. For example: http://us3.php.net/preg_replace Say what you > will about PHP, but it's documentation for each function it provides > is top notch. I really wish django had something like that for each > function it provides. > I think this kind of documentation is much less important in python projects. Of course it may be useful to have it in a browser window, but I tend to work with a python shell open all the time, so just typing help(function) (or function? in ipython) should give me the docstring and the function signature (and django's docstrings are great in general). > Yesterday I wanted to add the RegexValidator to my project, but > couldn't figure out how to import it because the documentation didn't > mention where the validators lives. I had to resort to googling > "RegexValidator django import" and came across some random pastebin > which had the import, and then went from there. That wasn't the first > time I had to do this. > For this kind of problem, i just grep django's code for the string I want. I know that not everyone likes to do this, and the lack of this kind of docs shouldn't impose a workflow, but since django is open source, and it's code is freely available the need for this kind of very specific documentation is not as obvious. I think what we should so is totally revamp the documentation for the > 1.3 release. I'm willing to do most of the work. I shouldn't be too > hard to do because right now everything is mostly already written, > just not organized very well. > I'm not saying the organization of the documentation can't be improved, but I really don't see the point of having this kind of auto generated documentation when we have great docstrings and resources to access them. -- You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-develop...@googlegroups.com. To unsubscribe from this group, send email to django-developers+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
