Electronics & Programming

develissimo

Open Source electronics development and programming

  • You are not logged in.

#1 Jan. 10, 2011 21:25:21

Simon W.
Registered: 2009-11-02
Reputation: +  0  -
Profile   Send e-mail  

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 listing
all methods and members of classes with some comment attached to them. They
also show the class heirachy, quick and simple. I spend more time searching
for minor stuff in the documention than writing code. The django project
should look into doxygen or some similar doc generator.

And this mailing list? It's so hard to find any existing answers quick,
google doesn't find none. I mean comon .. look at jQuery, you find what
you're looking in less than 2 sec using google. Why isn't there a proper
forum?

Am I the only one who frown upon this?

Cheers

--
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-us...@googlegroups.com.
To unsubscribe from this group, send email to
django-users+unsubscr...@googlegroups.com.
For more options, visit this group athttp://groups.google.com/group/django-users?hl=en.

Offline

#2 Jan. 10, 2011 21:30:29

Shawn M.
Registered: 2009-11-02
Reputation: +  0  -
Profile   Send e-mail  

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 who identify room
for improvement step up and volunteer their own time to fix the things they
want fixed. Do you have any spare time?

Shawn


--
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-us...@googlegroups.com.
To unsubscribe from this group, send email to
django-users+unsubscr...@googlegroups.com.
For more options, visit this group athttp://groups.google.com/group/django-users?hl=en.

Offline

#3 Jan. 10, 2011 21:49:14

m.
Registered: 2009-11-02
Reputation: +  0  -
Profile   Send e-mail  

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 very well expressed obviously)
complaint to bring it up to developers attention and see if there's
anyone else that thinks that I do.

Im not a beginner when it comes to programming and django was very
easy to learn but as soon as you start developing and want to tweak
stuff it's so hard to get fast detail documentation .. Im just curious
why the django project haven't set up any proper forum?

Again sorry for my unfriendly topicstarter.

On Jan 10, 10:30 pm, Shawn Milochik <sh...@milochik.com> wrote:
> 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 who identify
> room for improvement step up and volunteer their own time to fix the things
> they want fixed. Do you have any spare time?
>
> Shawn

--
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-us...@googlegroups.com.
To unsubscribe from this group, send email to
django-users+unsubscr...@googlegroups.com.
For more options, visit this group athttp://groups.google.com/group/django-users?hl=en.

Offline

#4 Jan. 10, 2011 21:59:49

Sam W.
Registered: 2009-11-02
Reputation: +  0  -
Profile   Send e-mail  

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

--
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-us...@googlegroups.com.
To unsubscribe from this group, send email to
django-users+unsubscr...@googlegroups.com.
For more options, visit this group athttp://groups.google.com/group/django-users?hl=en.

Offline

#5 Jan. 10, 2011 22:02:53

O.
Registered: 2009-11-02
Reputation: +  0  -
Profile   Send e-mail  

Django's documention is horrible


On Mon, Jan 10, 2011 at 4:53 PM, Sam Walters <mr.sam...@gmail.com> 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 and simple.
>
> I just look at the source itself for this.
>

or use pydoc

>
>
> cheers
>
> sam_w
>
> --
> You received this message because you are subscribed to the Google Groups
> "Django users" group.
> To post to this group, send email to django-us...@googlegroups.com.
> To unsubscribe from this group, send email to
> django-users+unsubscr...@googlegroups.com<django-users%2bunsubscr...@googlegroups.com>
> .
> For more options, visit this group at
>http://groups.google.com/group/django-users?hl=en.
>
>


--
Cristian Salamea
@ovnicraft

--
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-us...@googlegroups.com.
To unsubscribe from this group, send email to
django-users+unsubscr...@googlegroups.com.
For more options, visit this group athttp://groups.google.com/group/django-users?hl=en.

Offline

#6 Jan. 10, 2011 22:05:33

Chris C.
Registered: 2009-11-02
Reputation: +  0  -
Profile   Send e-mail  

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 Mon, Jan 10, 2011 at 5:02 PM, Ovnicraft <ovnicr...@gmail.com> wrote:

>
>
> On Mon, Jan 10, 2011 at 4:53 PM, Sam Walters <mr.sam...@gmail.com> 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 and simple.
>>
>> I just look at the source itself for this.
>>
>
> or use pydoc
>
>>
>>
>> cheers
>>
>> sam_w
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "Django users" group.
>> To post to this group, send email to django-us...@googlegroups.com.
>> To unsubscribe from this group, send email to
>> django-users+unsubscr...@googlegroups.com<django-users%2bunsubscr...@googlegroups.com>
>> .
>> For more options, visit this group at
>>http://groups.google.com/group/django-users?hl=en.
>>
>>
>
>
> --
> Cristian Salamea
> @ovnicraft
>
> --
> You received this message because you are subscribed to the Google Groups
> "Django users" group.
> To post to this group, send email to django-us...@googlegroups.com.
> To unsubscribe from this group, send email to
> django-users+unsubscr...@googlegroups.com<django-users%2bunsubscr...@googlegroups.com>
> .
> For more options, visit this group at
>http://groups.google.com/group/django-users?hl=en.
>

--
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-us...@googlegroups.com.
To unsubscribe from this group, send email to
django-users+unsubscr...@googlegroups.com.
For more options, visit this group athttp://groups.google.com/group/django-users?hl=en.

Offline

#7 Jan. 10, 2011 22:07:40

Javier G.
Registered: 2009-11-02
Reputation: +  0  -
Profile   Send e-mail  

Django's documention is horrible


On Mon, Jan 10, 2011 at 5:02 PM, Ovnicraft <ovnicr...@gmail.com> 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 the right tool for Python code references is pydoc, which _is_
very complete in Django.

maybe it would be a nice gesture to add pydoc's output to the online docs?

--
Javier

--
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-us...@googlegroups.com.
To unsubscribe from this group, send email to
django-users+unsubscr...@googlegroups.com.
For more options, visit this group athttp://groups.google.com/group/django-users?hl=en.

Offline

#8 Jan. 10, 2011 22:09:22

Shawn M.
Registered: 2009-11-02
Reputation: +  0  -
Profile   Send e-mail  

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 think there's a phpBB-style form anywhere, such as is used by Ubuntu
(and a million others). Maybe it would be a good idea, maybe not. Let's discuss!

One thing that strikes me as a member of this list and someone who tries to
keep up with the world of Django is that it's always changing. So a forum
thread from six months ago might be outdated. The best way is to become a part
of the community, answer and ask questions on this list, and eventually you'll
just be steeped in it. That's my best recommendation.

And as multiple others have said as I was composing this, check out the code!
It's very readable.

Shawn




--
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-us...@googlegroups.com.
To unsubscribe from this group, send email to
django-users+unsubscr...@googlegroups.com.
For more options, visit this group athttp://groups.google.com/group/django-users?hl=en.

Offline

#9 Jan. 10, 2011 22:14:24

m.
Registered: 2009-11-02
Reputation: +  0  -
Profile   Send e-mail  

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 a look at the API doc of a 3D library called
Ogre3dhttp://www.ogre3d.org/docs/api/html/annotated.htmlDo you see what I mean? Fast, simple, clean and online! Very
convenient!

On Jan 10, 10:53 pm, Sam Walters <mr.sam...@gmail.com> 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 and simple.
>
> I just look at the source itself for this.
>
> cheers
>
> sam_w

--
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-us...@googlegroups.com.
To unsubscribe from this group, send email to
django-users+unsubscr...@googlegroups.com.
For more options, visit this group athttp://groups.google.com/group/django-users?hl=en.

Offline

#10 Jan. 10, 2011 22:23:40

m.
Registered: 2009-11-02
Reputation: +  0  -
Profile   Send e-mail  

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 ask as a last resort and I think many
people agree with this.

On Jan 10, 11:09 pm, Shawn Milochik <sh...@milochik.com> wrote:
> 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 think there's a phpBB-style form anywhere, such as is used by Ubuntu
> (and a million others). Maybe it would be a good idea, maybe not. Let's
> discuss!
>
> One thing that strikes me as a member of this list and someone who tries to
> keep up with the world of Django is that it's always changing. So a forum
> thread from six months ago might be outdated. The best way is to become a
> part of the community, answer and ask questions on this list, and eventually
> you'll just be steeped in it. That's my best recommendation.
>
> And as multiple others have said as I was composing this, check out the code!
> It's very readable.
>
> Shawn

--
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-us...@googlegroups.com.
To unsubscribe from this group, send email to
django-users+unsubscr...@googlegroups.com.
For more options, visit this group athttp://groups.google.com/group/django-users?hl=en.

Offline

Board footer

Moderator control

Enjoy the 18th of August
PoweredBy

The Forums are managed by develissimo stuff members, if you find any issues or misplaced content please help us to fix it. Thank you! Tell us via Contact Options
Leave a Message
Welcome to Develissimo Live Support