Re: Django's documention is horrible

On Jan 12, 7:18 am, Mike Dewhirst wrote: > OK - so we need an intro to the documention which describes the timeline > of a typical* developer transitioning from beginner to guru and the docs > which should be of interest at successive stages during that transition. > > *typical - I know there ai

Re: Django's documention is horrible

OK - so we need an intro to the documention which describes the timeline of a typical* developer transitioning from beginner to guru and the docs which should be of interest at successive stages during that transition. *typical - I know there ain't such a person. However, there ought to be a "

Re: Django's documention is horrible

Although it might be nice to have api docs online, you have to say that django has excellent high level docs (django docs site) and low lvl docs (code is well py-documented -in the source). Epydocs, and other doc alternatives - automatic or semi automatic doc generators like pydoctor, sphinx (a qui

Re: Django's documention is horrible

My 2c (as a lowly Django user). Having used Another Large Web Framework (open source) for nearly 10 years, I can say with confidence that Django's human-written documentation is superb. The ALWF documentation was never kept up-to-date (and the online API did not really help much) - the user's had

Re: Django's documention is horrible

The reason I chose django in the first place was the documentation. Compared to everything out there, it was incredible. Back then it also had a helpful comments section on each page where people chimed in to clarify various parts of the document. It reads like a text book, which is a big help wh

Re: Django's documention is horrible

On Tue, Jan 11, 2011 at 05:12:46PM -0600, Kevin Monceaux wrote: > Do you mean like the reference manual one can build from Django > source? The above wasn't entirely clear. I meant the manual one can build from the documentation source code which is included the Django source tarball. -- K

Re: Django's documention is horrible

On Tue, Jan 11, 2011 at 12:36:26AM -0800, mrmclovin wrote: > I guess your post should be replaced by my first one :). It's exactly > what I was trying to say: django need a reference manual to complement > the existing documentation. Do you mean like the reference manual one can build from Django

Re: Django's documention is horrible

On Jan 11, 3:36 am, mrmclovin wrote: > On Jan 11, 7:44 am, Sam Lai wrote: > > > > > > > > > > > On 11 January 2011 13:39, Christophe Pettus wrote: > > This isn't about patches to the existing docs (which are great for > > their purpose). It is about Django missing an API reference manual, > >

Re: Django's documention is horrible

On 2011-01-11, at 14:39 , shofty wrote: > but by the same token, ive not seen a mailing list that hasn't made me > want to gouge my own eyes out. its not a great place for reading code > is it? you can't do a [code] [/code] to isolate an example on it. If you configure your MUA to display text with

Re: Django's documention is horrible

but by the same token, ive not seen a mailing list that hasn't made me want to gouge my own eyes out. its not a great place for reading code is it? you can't do a [code] [/code] to isolate an example on it. the point im trying to make is that your choice isn't necessarily my choice. who is right? (

Re: Django's documention is horrible

On Jan 11, 1:51 pm, Masklinn wrote: > On 2011-01-11, at 13:47 , mrmclovin wrote:> On Jan 11, 9:59 am, Masklinn > wrote:y? > > Because you don't have to compile APIDocs to be able to use Django. > Okey, the analogy was not about django itself, but a reference manual. > In fact the APIDocs are

Re: Django's documention is horrible

On 2011-01-11, at 13:47 , mrmclovin wrote: > On Jan 11, 9:59 am, Masklinn wrote: >> >> This analogy makes no sense whatsoever, I fear. > > hehe why? Because you don't have to compile APIDocs to be able to use Django. In fact the APIDocs are pretty irrelevant to a new Django user, and the handc

Re: Django's documention is horrible

On Jan 11, 9:59 am, Masklinn wrote: > > This analogy makes no sense whatsoever, I fear. hehe why? Wouldn't it be nice to host an online reference instead of letting users "compile" the source themselves? Guess I will try pydoc now and get my own html reference. I hope next time someone is lookin

Re: Django's documention is horrible

On 2011-01-11, at 09:36 , mrmclovin wrote: > If you bought a game, would you rather like to get info on how to > compile the game in order to play it.. or just install it and play it? > This analogy makes no sense whatsoever, I fear. -- You received this message because you are subscribed to the

Re: Django's documention is horrible

On 2011-01-11, at 07:44 , Sam Lai wrote: > On 11 January 2011 13:39, Christophe Pettus wrote: >> >> On Jan 10, 2011, at 1:25 PM, Simon W wrote: >> >>> For such a good web framework it's a shame that the documention is not >>> structured well .. at all. >> >> I have no doubt that the project wo

Re: Django's documention is horrible

On Jan 11, 7:44 am, Sam Lai wrote: > On 11 January 2011 13:39, Christophe Pettus wrote: > This isn't about patches to the existing docs (which are great for > their purpose). It is about Django missing an API reference manual, > something like .NET Class Library Reference > (http://msdn.microsoft

Re: Django's documention is horrible

On Tue, Jan 11, 2011 at 12:44 AM, Sam Lai wrote: > This isn't about patches to the existing docs (which are great for > their purpose). It is about Django missing an API reference manual, > something like .NET Class Library Reference > (http://msdn.microsoft.com/en-us/library/gg145045.aspx), PHP's

Re: Django's documention is horrible

On Mon, 2011-01-10 at 22:25 +0100, Simon W wrote: > Am I the only one who frown upon this? the documentation is excellent - structure needs revamping as it is very difficult to find any thing unless one knows the key words. It was far better uptil circa .96. I have been working on a small scheme o

Re: Django's documention is horrible

On 11 January 2011 13:39, Christophe Pettus wrote: > > On Jan 10, 2011, at 1:25 PM, Simon W wrote: > >> For such a good web framework it's a shame that the documention is not >> structured well .. at all. > > I have no doubt that the project would be more than receptive to doc patches > to fix t

Re: Django's documention is horrible

On Jan 10, 2011, at 1:25 PM, Simon W wrote: > For such a good web framework it's a shame that the documention is not > structured well .. at all. I have no doubt that the project would be more than receptive to doc patches to fix the problem. -- -- Christophe Pettus x...@thebuild.com --

Re: Mailing Lists Vs. Forums (Was: Django's documention is horrible)

On Tue, Jan 11, 2011 at 07:51:55AM +0800, Russell Keith-Magee wrote: > I am yet to meet an online forum interface that doesn't make me want > to gouge my own eyes out. For my money, email is a vastly preferable > interface in almost every respect. Google's Groups could certainly > do with some wo

Re: Django's documention is horrible

On Mon, Jan 10, 2011 at 6:51 PM, Russell Keith-Magee wrote: > I am yet to meet an online forum interface that doesn't make me want > to gouge my own eyes out. For my money, email is a vastly preferable > interface in almost every respect. wholeheartedly agree. (and i'm sure not to be the only on

Re: Django's documention is horrible

On Tue, Jan 11, 2011 at 5:49 AM, mrmclovin wrote: > Im just curious > why the django project haven't set up any proper forum? I'll address this one. I am yet to meet an online forum interface that doesn't make me want to gouge my own eyes out. For my money, email is a vastly preferable interface

Re: Django's documention is horrible

On Mon, Jan 10, 2011 at 3:25 PM, Simon W wrote: > For such a good web framework it's a shame that the documention is not > structured well .. at all. It consists of massive text put on a page with > some random examples. But examples is all there is. In other languages and > frameworks I'm used to

Re: Django's documention is horrible

On Jan 10, 2011, at 5:23 PM, mrmclovin wrote: > Yes, being part of the community is good. But to base help and > solutions by ask&answer is not good for documentation IMO. I don't > like to ask questions because then I have to explain the problem, word > everything right and then wait for an answ

Re: Django's documention is horrible

you can see or check the django book . i think it's excellent. i am new to django also web, i love django with read it. i want to write a web site immidiately. 2011/1/10 Shawn Milochik > Welcome to the community, and congratulations on putting your best foot > forward! > >

Re: Django's documention is horrible

Ummm... I think thats the first time I've ever heard anyone say that django's documentation sucks. Sent from my iPhone On Jan 10, 2011, at 4:25 PM, Simon W wrote: > Hey, > For such a good web framework it's a shame that the documention is not > structured well .. at all. It consists of massi

Re: Django's documention is horrible

Yes, being part of the community is good. But to base help and solutions by ask&answer is not good for documentation IMO. I don't like to ask questions because then I have to explain the problem, word everything right and then wait for an answer. I prefer to find the answer quick on my own and only

Re: Django's documention is horrible

I usually end up in that way too. But I don't find it convenient. There's lots of class relations and going back and forth is clumsy. Also in most cases Im just after the specification of a class or where it's defined and it takes longer time if you have to scroll down the source code as well. Have

Re: Django's documention is horrible

I agree that searching the Google group isn't always the most rewarding. There are many blogs maintained by long-time Django users (and developers), but obviously this is no replacement for a consolidated forum. There is the official wiki as well: http://code.djangoproject.com/wiki/ I don't thi

Re: Django's documention is horrible

On Mon, Jan 10, 2011 at 5:02 PM, Ovnicraft wrote: >> I just look at the source itself for this. > > or use pydoc right. i think what Simon means (but still can't articulate) is the difference between explanations (which are great in the Django docs) and references (which aren't so good). but th

Re: Django's documention is horrible

Yup, that is my approach... The Django sourcecode is eminently readable and well-organized and most of it has documentation associated with it. You can jump into a shell and use the help() command to view API documentation like you requested. e.g. >>> help('django.contrib.auth.models.User') On

Re: Django's documention is horrible

On Mon, Jan 10, 2011 at 4:53 PM, Sam Walters wrote: > Hi, > My approach with regard to: > > > frameworks I'm used to have at least a well structed API documention > listing > > all methods and members of classes with some comment attached to them. > They > > also show the class heirachy, quick an

Re: Django's documention is horrible

Hi, My approach with regard to: > frameworks I'm used to have at least a well structed API documention listing > all methods and members of classes with some comment attached to them. They > also show the class heirachy, quick and simple. I just look at the source itself for this. cheers sam_w

Re: Django's documention is horrible

My apologies, didn't mean to sound like an a-hole. I do appreciate django very much for what it is. The library is beautiful really, but the documentation is the opposite. I wish I could spend time to help improve the documentation, but I have not the time. Instead I thought I'd make this (not ve

Re: Django's documention is horrible

Welcome to the community, and congratulations on putting your best foot forward! I am certain that your non-confrontational tone and obvious appreciation for all the hard work done for free by volunteers has endeared you to all of us. One minor suggestion: In the community, we like to see people

Django's documention is horrible

Hey, For such a good web framework it's a shame that the documention is not structured well .. at all. It consists of massive text put on a page with some random examples. But examples is all there is. In other languages and frameworks I'm used to have at least a well structed API documention listi